Editing Your Own Documentation

Technical writers sometimes fall into the trap of thinking that the user is stupid. I have often heard technical writers say things like "well, if the user can't figure that out, maybe he’s in the wrong job!"

It is my opinion that users should not have to figure anything out. They do not read our documentation for fun, or to expand their minds, or to improve their ability to think. In fact, users would much rather not read our documentation at all. Technical documentation is usually nothing more than a necessary evil, something that users want to get through as quickly and as painlessly as possible. Our job is to make the documentation easy and painless to read. It should never cause a moment's puzzlement, stress, worry, or annoyance. The user should never have to say "huh?"

The main cause of user incomprehension is careless writing. While you may believe that this point is obvious, in fact, I regularly see user guides that contain spelling, grammatical, and punctuation errors, leaps of logic, ambiguities, missing words, and incorrect vocabulary, as well as such peculiar formatting as to make navigation difficult. Even the best writers make these mistakes at times.

While it is better to have someone else review and edit your documents, you can successfully eliminate many problems (all of which are described in more detail in other articles in this site) commonly found in technical documents by following the list below.

In the electronic version of the document:

  • Perform a spell-check on the document.
  • Search the document for the following usage infractions:
    • passive voice (search for is, are, were, by, etc.); replace with the active voice
    • future tense (search for will); replace with the present tense
    • conditional tense (search for ould); replace with the present tense
    • contractions (search for n't and 've); replace with full words
    • non-parallel construction (search for bulleted lists); ensure that the first word of each list item is of the same type (noun, verb)
    • unclear antecedent (search for "This"); ensure that "This" is followed by a noun and not a verb
    • and/or; replace with ". . . or . . ., or both"
    • forbidden words (search for "kill," "abort," and any other words that your company has deemed inappropriate or inexact)
  • Search the document for broken links.
  • Perform another spell-check.

After you have completed the steps above, print the document and look for any obvious problems in the following:

  • headers and footers (incorrect position of elements, incorrect text)
  • headings (inconsistent capitalization, improper hierarchy)
  • pagination (incorrect position of page number, chapters beginning on a left-hand page, Roman numerals where there should be Arabic numerals and vice versa)
  • TOC (incorrect alignment, tab positions, and hierarchy)
  • table format (improper page breaks, poor alignment)

Finally, read through the entire document while imagining that you are an inexperienced user; rewrite anything that could be misunderstood.