Checks You Can Do Yourself

You can do a variety of checks on your writing during the development of your documentation, in the following areas.

5.2.1. Top-Level Checks

You can perform the following top-level checks regularly during documentation development:

  • Wordcount

    As soon as a sentence or a procedure step starts to look suspiciously long, do a wordcount. See Section 1.2 ― Golden Rules, Golden Rule 1.

  • Spellcheck

    Run regular spellchecks. Make sure that agreed terms from Appendix A ― Recommended Terminology are in your spellchecker dictionary.

  • Pronouns search

    Search for the following pronouns:

    • It
    • They
    • Them

If you find any of the above pronouns, rewrite the sentences to eliminate the pronoun.

5.2.2. Top Ten Topics to Watch Out For

The following table lists the top ten topics that you need to watch out for when you review your work, or when you perform a peer review for a colleague. Review the documentation against the typical problem areas listed in the table. The problem areas in the table are not exhaustive, you may encounter more pitfalls during your review. The table provides you with cues so that you can review your work with these topics and problem areas in mind. You can find advice about how to deal with these topics in other sections of this style guide.

Topic Typical Problem Areas
Accuracy
  • Functions differ from the description.
  • Functions are not described
  • Functions are referred to using different terminology from the user interface.
  • Functions are described that do not exist.
  • The description provides irrelevant and possibly confusing information.
Clarity
  • Ambiguous statements
  • Inconsistency
  • Unexplained events
  • Undefined terms
  • Vague, defensive language
Editorial
  • Repeated words
  • Misspelled words
  • Typographical errors
  • Missing words
  • Verbs in the wrong tense
Grammar and Syntax
  • Tenses other than the present tense
  • Long sentences joined by conjunctions, such as and.
  • Long sentences with confusing subordinate clauses
  • Incomplete sentences that leave out the articles
  • Over-elaborate sentence structure and syntax.
Graphics
  • Wrong graphic referred to in text.
  • Graphic has different features from the description.
  • Unnecessary use of formal figures.
  • Incorrect use of informal figures.
  • Graphics do not adhere to graphics style rules.
Information Design
  • Series of points are described in prose rather than an itemized list.
  • Sequences of actions are described in prose rather than a numbered list.
  • Topics are described in sequential paragraphs rather than in tables.
  • Information is ordered incorrectly within a document.
  • Unclear or insufficient examples to support the descriptions.
Legal
  • Unsubstantiated claims
  • Incorrect description of functions
  • Insufficient notice of potential damage or hazard
  • Statements about future features
  • Statements about competing products
Punctuation
  • Use of slash, and and/or
  • Inconsistent use of hyphens and dashes
  • Inappropriate use of parentheses and brackets
  • Incorrect use of apostrophes
  • Incorrect use of quotation marks
Style and Usage
Tone
  • Jargon
  • Colloquial language
  • Humor
  • Culture-specific references
  • Gender-specific language
  • Condescension