A quick writing checklist for technical writers

Technical writers spend a lot of time understanding new software, products, services and how they function. Reading functional specification documents, test notes, spending time with subject matter experts take a lot of time in a day of a technical writer. When you are ready with all the information to write, it is important that you also have a writing checklist handy to refer to while composing documentation.

Following is a quick checklist that helps you focus on your writing by pointing out the most essential things to keep in mind.

Checklist for technical writers

Present tense and active voice

Always use present tense and use active voice. Do not say you will do this, rather say, you do this. Use ‘will’ and ‘shall’ only when you want to denote something in the future; otherwise, use the present tense. Minimize the use of gerunds (verbs ending in ‘ing’). Gerunds can get confusing and can cause a problem during translation.

Example:

Incorrect way: Advocate requesting State assistance when available.

Correct way: Request State assistance when available.

Simple sentences

Use simple declarative sentences to state who does what action. Employ active voice to improve complicated sentences. Split the long sentences into two and express one idea per sentence to make it user-friendly.

Example:

Incorrect way: A programmer would see the flaw in this logic. He would correct it immediately.

Correct way: Programmers would see the flaw in this logic. They would correct it immediately.

Gender neutrality

No personal pronoun in English refers to both genders. He/she alternative is awkward. When discussing general categories of people, rewrite the sentence in the plural to avoid the issue of gender. Use gender-neutral nouns and pronouns, such as chair instead of chairman, and their, they, or them rather than he, she, her, or him.

Abbreviations and acronyms

The first time you use an abbreviation or acronym in a document, spell it out, even if you think your audience knows the term. The right format is to spell out the full word or phrase, followed by the abbreviation in parentheses.

Procedures

Procedures are the heart of the user guide. For each task, document the following:

Explain how to get started. For example:

• Specific settings to be installed
• Installing a plugin
• A specific version of the software (Java) to be installed
• Describe the different functions of the system.
• Provide cautions, warnings, and recommendations.
• For each procedure, identify where in the application you perform this task, input operations, and expected results.
• Include a screenshot that helps the reader understand the task.
• Highlight the required parameters, optional parameters, default options, and order/syntax etc.
• Provide examples.
• Identify the known issue, likely errors, possible causes, and resolutions.

Error messages and recovery procedures

While writing error messages, document all error messages, identify root cause and suggest recovery procedures in the error message. Always add an option to contact someone/telephone number to assist users.

Reference

Identify and describe all system capabilities, for example:

• Describe the purpose of different buttons on the menu bars
• What happens if they get greyed-out
• How to change (screen/window) this
• Why this occurred
• How to reset window layout
• Describe the purpose of each field
• Identify mandatory settings, minimum or maximum settings, recommendations, and data input types.

Lists

Lists save readers time by allowing them to see specific items, questions, or directions at a glance. They allow key ideas to stand out from the surrounding text.

Bulleted lists present a series of similar items. Numeric lists denote sequential items or items ranked in importance. Numbers also help readers refer to particular items in sequence.

Items in all lists should have parallel structure. Do not mix items that are actions and results. If one list item is a complete sentence, all should be complete sentences.

Tips for using lists

• List only comparable items.
• Use parallel structure throughout.
• Use short sentences, phrases, or words.
• Provide adequate transitions before and after lists.
• Use bullets when rank or sequence is not important.

Figures and tables

Figures and tables provide an instant understanding of complex information. They must be accurate, meaningful, and described in the text. Keep figures and tables in close proximity to the text that describes them so that the reader does not have to flip back and forth between the figure or table and its description. Always refer to the figure or table by number, not ‘above’ or ‘below’.

Always number figures and tables in sequence. If your pagination is sequential through the text, such as pages 1 to 204, number figures and tables sequentially. For example, if there are 83 figures, label them Figure 1 through Figure 83. If there are 18 tables, label them Table 1 through Table 18.

Cross-references

Use a cross-reference to guide the reader to the location. Cross-references help the reader know where more information about a topic is available. Use cross-references throughout the text to refer to information that also relates to the current discussion. A common format is (See <chapter>, <section>).

Redundancy

Avoid using the same words twice in a sentence. After you write a sentence, look it over and ask whether there are any words you can cut without affecting the meaning. Avoid words and phrases that do not add meaning to a sentence. Some words and phrases to avoid are:

Actually, as you know, at the present moment in time (replace with ‘now’, in order to (replace with ‘to’), in terms of, moreover, utilize, utilization (replace with ‘use’), very etc.

Colon

A colon marks a pause for explanation, expansion, enumeration, or elaboration. Use a colon to introduce a list: item one, item two, and item three. Use a colon to provide corroborating evidence for a statement that precedes the colon or to provide an example.

Use of E.g. versus i.e.

The abbreviation e.g. is for the Latin exempli gratia, which means “for example.” I.e. is short for the Latin id est, which means that is. A comma should follow both abbreviations. Because these terms are often confused, it’s often clearer to use the words for example or that is instead of these abbreviations.

Links

Links help to connect information between topics. Check all the links to ensure they are working. Make sure they take users directly to the resource mentioned rather than making them navigate to it from a landing page.

Images and screenshots

Images help users to understand the technical information. While using screenshots, ensure:

• Images and screenshots are captured with data in them. For example, the login screen has name and password entered in the screenshot.
• If possible, keep them at the same width and height. (use Jpeg quality images)
• All images are highlighted in the same way.
• Crop the image to highlight the most useful part.
• Avoid special effects, such as jagged edges, which can look inappropriate or dated.

If you are looking for detailed instructions on writing well, refer to the Microsoft Style Guide, the Chicago Manual of Style, the IBM style guide, the elements of style by Strunk and White etc. These are well established and most widely used style guides in the technical writing community. You can choose to follow one of the established guides or can create a specific one for your company.