I have been writing software documentation for the past twelve years, and it amazes me how many IT professionals like to push documentation to the back burner. Quality documentation alone can save a project because many times there is a turnover of programmers and developers, so quality documentation ensures smooth sailing in current and future projects.

If I had to summarize ten truly important foundation points that establish quality software documentation, here they are, reflecting upon my twelve years of technical writing experience and additional years, beforehand, working as a software trainer:

1. Short Sentences, Always. When you write about technical things, long sentences can confuse the reader. It is best to use short sentences to ensure that your reader is following you.

2. Consistent Terms, Also. When you write about a system of some kind, there are certain terms that will be repeated as you work your way through the technical document. Make sure you spell out these acronyms or technical expressions at the outset of the document. This way, the reader will not think you are talking “geek” but rather are being sincere in your efforts to explain something.

3. Clear Screen Shots. I am a visual man, and so are many others out there. It is always a great thing to be able to show, visually, what you are discussing. A nicely selected screen shot, especially with relevant data, will always enhance your documentation and help the reader really understand what you are presenting.

4. Relevant Diagrams. Just like quality screen shots, nice diagrams also will help the reader to understand your points, but also will prepare them for future text that you will be presenting in the document. A nice diagram gives the reader a “visual” preparation for what you have not yet discussed or presented. It gives them a chance also to recover from perhaps difficult text that they cannot understand, but because you gave them a nice diagram, now perhaps they understand.

5. Know Your Reader. This goes without saying. The ones reading technical documentation about software are not just users, but also developers and quality assurance personnel. Make sure you include a few “techie” comments or observations to remind them that you are aware they are taking the time from their busy schedule to read your documentation.

6. Give Examples. I love to read and have examples. Things are so much clearer afterwards! Yes, all readers, both technical and non-technical most surely like to challenge their understanding with examples, especially when you are using relevant data and models, putting the system to the test.

7. Short Paragraphs. Just like my first point of short sentences, it is good to have short paragraphs. Do not cover more than one important concept per paragraph. This keeps the reader with a sense of confidence as he or she is reading. OK?

8. Detailed Table of Contents. After you have written your documentation, create a detailed Table of Contents, because this way nobody has to “look for something”. It will be immediately found because you took the time to provide a nice “document” map in the form of a good TOC.

9. Detailed Index. In the same way it is good to have a meaningful and descriptive Table of Contents, it is also good to be able to have a nice index that covers, alphabetically, important concepts. Perhaps your document is really long and the reader cannot find a concept in the TOC. With a nice index, he or she will find the concept.

10. Publishing Your Work. The three most popular formats for final documentation are (1) Microsoft Word or another text presentation program like Adobe Acrobat, (2) Microsoft Help in a compiled .CHM file that runs as a stand-alone desktop application, and (3) Web Help that can be created with programs like Robohelp. Choose the output that will be best for your audience