A Baker’s Dozen Tips for Better Technical Writing

Good writers know that all writing can be improved. Starting right makes for less work. Here are thirteen tips to help make your technical writing great.

1- Be clear and concise

This may be your only chance to engage the reader and gain trust. Aim for text that is clear without ambiguity, succinct yet comprehensive. Always keep the task in mind:

• Tell the reader what the feature does and how to use it.
• It’s acceptable to refer them to another topic for related information.
• When describing a specific task (e.g., changing text background color), focus on that task and avoid unrelated details.

2- Be precise

Consider your audience, especially novice users. Be exact when describing the interface:

• Don’t say: “Use Preferences to set different options.”
• Instead, say: “Click System > Options to view and modify software settings, such as display, cursor, ribbon, and fonts.”

3- Put technical details where they make sense

Avoid overloading descriptions with unnecessary information:

• Instead of: “Insert the enclosed ISO-certified 4.7 GB DVD disc in the CD/DVD drive.”
• Consider: “Insert the enclosed DVD into the disc drive.”
• Include detailed technical specifications in an appendix or dedicated technical section.

4 - Keep courtesy out of it

In technical documentation, omit phrases like “please” and “thank you.” For example:

• Instead of: “Please contact System Innovator support for assistance with any issues.”
• Use: “Contact System Innovator support for assistance with any issues.”

5 - Use consistent terminology

Choose a single term for each concept and use it consistently throughout the document. For example, decide whether to use “computer,” “system,” “hardware,” or “device” and stick with it.

6 - Write for localization

Consider a global audience:

• Avoid US-centric examples and phrases.
• Be cautious with colloquial terms that may be offensive in other cultures.
• Consider cultural differences in color symbolism for warnings and errors.

7 - Be smart with visuals

When using graphics and screenshots:

• Ensure they match your written descriptions.
• Regularly check and update interface screenshots throughout the project.
• Avoid overloading graphics with too many callouts or annotations.
• Put the annotations on a separate layer. That makes the image easier to update.
• If you add more to a screenshot than you’re writing about, consider simplifying or creating multiple images.

8 - Spell out acronyms (SOA)

Not every reader is familiar with industry-specific acronyms. Spell out acronyms on first use.

• Example: “Note any changes to glucose (GLU) or blood urea nitrogen (BUN) levels in the worksheet and set suspect samples to Hold, Review, Release (HRR).”
• Consider using tools that allow for expanded acronyms in online documentation.

9 - Speak plainly

Avoid pretentious prose. Use simpler alternatives for complex words or phrases. Use method, not methodology. Use skill, not proficiency.

10 - Use lists

Lists help break up text and make information easier to scan and understand.

Instead of:

Use the Backup menu to back up data, restore data, test existing backups, or import data from other Expar systems.

Use this:

Use the Backup menu to:

• Back up your data
• Restore your data
• Test existing backups
• Import data from other Expar systems

While the text looks longer, it is easier for a user to scan.

11 - Use active voice

Active voice is generally clearer and more direct than passive voice:

• Passive: “By Thursday, you should have read the reference material.”
• Active: “Read the reference material by Thursday.” Active voice typically requires less text, clearly identifies the actor, and is often easier to translate.

12 - Hire an editor

As a professional writer, consider hiring a professional editor to:

• Identify copy and organizational problems.
• Make suggestions for improvement.
• Provide an external perspective on your work.

13 - Keep communications open

Remember, your team is your first audience, even if they aren’t your primary audience. Maintain open lines of communication with your team:

• Involve team members early in the review process.
• Actively seek their feedback.
• Use their comments and criticisms to improve the documentation.