Document Quality

• Document quality is as important as program quality.
• Without information on how to use a system or how to understand it, the utility of that system is degraded.
• Producing good documents is neither easy nor cheap and the process is at least as difficult as producing good programs.
• Documentation standards should describe exactly what the documentation should include and should describe the notations to be used in the documentation.
• Within an organization, it is useful to establish a standard for documents and require that all documents conform to that format.
• The standard for documents might include:

1. a description of a front-cover format to be adopted by all documents,
2. page numbering and page annotation conventions,
3. methods of reference to other documents, and
4. the numbering of headings and sub-headings.

Writing style

• The most fundamental factor affecting documentation quality is the ability of the writer to construct clear and concise technical prose.
• Good documentation requires good writing.
• Writing documents well is neither easy nor is it a single-stage process. Written work must be written, read, criticized and then rewritten, and this process should continue until a satisfactory document is produced.
• It is impossible to present a set of rules which govern exactly how to set about this particular task. Technical writing is a craft rather than a science and only broad guidelines about how to write well may be given.

Guidelines for writing software instruction manuals:

1. Use active rather than passive tenses. It is better to say ‘You should see a flashing cursor at the top left of the screen’ rather than ‘A flashing cursor should appear at the top left of the screen’.
2. Do not use long sentences which present several different facts. It is better to use a number of shorter sentences. Each sentence can then be assimilated on its own. The reader does not need to maintain several pieces of information at one time in order to understand the complete sentence.
3. Do not refer to information by reference number alone. Instead, give the reference number and remind the reader what that reference covered. For example, racher than say ‘In section 1.3…’ you should say ‘In section 1.3, which described software evolution’.
4. Itemize facts wherever possible. It is usually clearer to present facts in a list rather than in a sentence. You might have found this set of guidelines harder to read if they hadn’t been itemized. Use textual highlighting (Italics or underlining) for emphasis.
5. If a description is complex, repeat yourself . It is often a good idea to present two or more differently phrased descriptions of the same thing. If the reader fails to completely understand one description, he or she may benefit from having the same thing said in a different way.
6. Don’t be verbose. If you can say something in five words do so, rather than use ten words so that the description might seem more profound. There is no merit in quantity of documentation. Quality is more important.
7. Be precise and define the terms you use. Computing terminology is very fluid and many terms have more than one meaning. Therefore, if specialized terms (such as module or process) are used, make sure that your definition is clear. If you need to define a number of words or if you are writing for readers with little or no knowledge of computing terminology, you should provide a glossary with your document. This should contain definitions of all terms that might not be completely understood by the reader.
8. Keep paragraphs short. As a general rule, no paragraph should be made up of more than seven sentences. This is because of short-term memory limitations. Our capacity for holding immediate information is limited, so by keeping paragraphs short all of the concepts in the paragraph can be maintained in short-term memory.
9. Make use of headings and sub-headings. These break up a chapter into parts which may be read separately. Always ensure that a consistent numbering convention is used for these.
10. Use grammatically correct constructs and correct spelling. To boldly go on splitting infinitives (like this) and to misspell words (like mispell) irritates many readers and reduces the credibility of the writer in their eyes.

Documentation tools

• There is a variety of software tools available to help with the production of documents. In general, documentation should be produced and stored on the same computer as is used to develop the system software.
• The most important documentation tool is a powerful editing system which allows documents to be generated and modified.
• A general-purpose text editor may be used for this task or a word processing system may be preferred.

Guidelines for selecting documentation tools:

1. The documentation is always on hand. Software developers or users need not search for a manual if they have access to the computer. In the case of user documentation, copies of this should be maintained on the same system as the application so that, again, reference to manuals may be unnecessary. The need for effective indexing of documents is particularly important when the documentation is maintained on-line. There is no point in having the information available if the reader cannot easily and quickly find the information required.
2. Documents are easy to modify and maintain This has the consequence that the project documentation is more likely to be kept up to date.
3. Documents may be automatically analysed The text can be analysed in various ways to produce different types of index and to check for spelling and typing errors.
4. Document production may be shared. Several individuals may work on the production of a document at the same time.
5. Documentation management is simplified. All associated documents can be collected under a common heading. The state of development of these documents may be ascertained. Configuration management tools may be used to maintain different versions of documents and to control changes.
6. Automatic information retrieval is feasible. Information retrieval systems may operate on documents retrieving all documents which contain particular keywords, for example.