Documentation is like sex; when it’s good, it’s very, very good, and when it’s bad, it’s better than nothing. – Dick Brandon
Technical documents such as User Guide, Configuration Guide, Installation Manual and others must be written in such a way that these translate the complex and puzzling into something that everyone and anyone can understand. When the user reads the user guide, it must obviously guide him and should not confuse him. The step-by-step guide must be clearly stated and logically arranged.
Careless writing will result to spelling, grammatical, and punctuation errors, leaps of logic, ambiguities, missing words, and incorrect vocabulary. These “common” mistakes confuse the readers thus, defeat the purpose of technical documents.
Although it is better to have someone review your work, you can avoid some problems by taking another time checking your document before sending or uploading it. Here are some tips to guide you.
- Perform a spell-check on the document
- Search the document for usage errors
- Search the document for broken links
- Perform another spell-check
Check the spelling
Read your document between lines. Read it carefully as if it is the first time you read it. Take extra attention on teh spelling of some commmon words. Have you noticed the errors in the preceding sentence? Yes, but some user guides still contain such errors. As technical writer, your responsibility is to deliver well-polished document.
This is very important. Try to search for is, are, were, by, etc. Read the sentence carefully. Do you need to replace passive voice with the active voice? Check also your tense. A newbie technical writer may write, “Press the start button. The system will …” In this case, “will” should be removed. It must be present tense.
Avoid: When you press the ENTER key, a warning message will appear on the screen.
Write: When you press the ENTER key, a warning message appears on the screen.
Note: Use SMALL CAPITALS for key names.
Another is the use of contractions like n’t and ‘ve). Replace them with full words. Instead of, “can’t” write “cannot”.
Check bulleted lists and ensure that the first word of each list item is of the same type. Begin each item in a bulleted list with a word of the same grammatical type. If the first item in a list begins with a verb, for example, then all the items in the list must begin with a verb.
Once again, remember that you write to help the readers.
Finally, read through the entire document while imagining that you are an inexperienced user; rewrite anything that could be misunderstood.
As Frederick Brooks advises, present to inform, not to impress; if you inform, you will impress.