How to Write Quality Documentation

Difference between version 2 and 3 - Previous - Next
'''How to Write Quality Documentation'''  is a guide to creating accurate,
readable, and useful documentation.



** 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".
   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."



** Page Authors **

   [PYK]:   

----
'''[aplsimple] - 2019-10-29 17:40:00'''

Good guidelines. Some simple remarks only:

   * fine to mention documentation generators like [Ruff!]

    * typo cleaners might be mentioned as well, e.g. to be applied to this wiki :)

    * probably, ''Each document must fall into'' is better than ''Each document should fall squarely into''

<<categories>> Documentation | Learn to Program