How to Write Quality Documentation

previous : Tips for writing quality software	up: Learn to Program	next : Testing

How to Write Quality Documentation is a guide to creating accurate, readable, and useful documentation.

Description

The three main categories of documentation are tutorial, guide, and reference. Each document should fall squarely into one and only one of these categories.

How to Write Reference Documentation

Reference documentation should resemble the script for a theatrical play, where routines are the actors and the script describes the story, the scene, and what the actors say and do. The following rules, listed roughly in order of priority, can help produce a quality reference document.

Content Guidelines

Make it unambiguous.: Rearrange phrases in a sentence so relationships between them are clear. "If the value of A is not NULL, it can be used to determine B" is better than "A can be used to determine B provided its value is not NULL".

Make it comprehensive.

Make it concise.: Include only necessary and helpful details. One of the most solid rules is that the fewer words there are, the more readable it is.

Provide each piece of information only once.: Repetition dulls the mind.

Elide filler words.: "Actually" and "here", are examples. "To" is better than "If you want to" or "In order to". Avoid "Note that", since the content should simply be removed if it isn't notable.

Choose the right place in structure of source code to provide context.: Instead of saying "check to see whether condition A has occurred and respond accordingly", place the comment within the conditional block of that says "Situation A has occurred. Respond accordingly."

Prefer a sequence of short logical statements over longer more prosaic descriptions.: Mental space is at a premium.

Prefer positive terminology.: It is easier and more memorable to build a mental model of what a system does than of what it doesn't do. "Ensure that" is better than "avoid".

Use a shorter phrase if it is just as informative, or sufficiently informative.: "The only reason to do A" might be replaced with "Do A because ...". "Note that A does" can be replaced with "A does ...". In particular, avoid the redundant "The reason for A is because...".

Find the right word.: Use precise terms instead of paraphrasing, choose more specific words over more general words, and use the most direct word or phrase. "When" is better than "any time".

Explain why before stating what.: "The resource doesn't exist, so set the variable to False." is better than "Set the variable to false because the resource doesn't exist."

Avoid the abstract.: Words that end in "ness", "tion", "ism", and "ity" indicate overly-academic phrasing. Instead, find a way to say that something does or is something else.

Grammar Guidelines

Prefer names over pronouns.: However, also use pronouns to avoid over-repetition of a name.

Use pronouns to make things more concise and natural: This doesn't contradict the previous rule. Rather they should both be applied to achieve a good sentence.

Make each pronoun as unambiguous as possible.: This often involves reording phrases within a sentence to bring the pronoun closer to the thing it refers to.

Use the present tense.: "Produces a list of names" is better than "Will produce a list of names".

Prefer singular form.: "Ensures that the indicated cached item is up-to-date" is better than "Ensures that cached items are up-to-date". However, plural form is sometimes the better choice for rules and constraints: "Identifiers beginning with a punctuation mark are reserved for system use".

Elide the subject.: "Produces a list of names" is better than "This function produces a list of names".

Use a third-party perspective in summaries.: "Produces a list" is better than "Produce a list".

Use an active voice.: "Calls function B" is better than "function B is called". "Performs B" is better than "Called to perform B".

Use the imperative mode to annotate the body of a routine or any step-by-step procedure.: "Check the value of B." instead of "Checks the value of B" or "We check the value of B".