Version 0 of How to Write Quality Documentation

Updated 2019-10-29 13:44:58 by pooryorick

How to Write Quality Documentation Provides

Description

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

How to Write Reference Documentation

The following rules, listed roughly in order of priority, can help produce a quality reference document:

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.
Prefer names over pronouns.
Pronouns can be useful though to avoid over-repetition of a name.
Make each pronoun as unambigous as possible.
This often involves reording phrases within a sentence to bring the pronoun closer to the thing it refers to.
Elide filler words.
"Actually" and "here", are examples. "To" is better than "If you want to" or "In order 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".
Use an active voice.
"Calls function B" is better than "function B is called".
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 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 te value of B".
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 becase ...". "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".

Page Authors

PYK