How to Write Quality Documentation

Difference between version 18 and 0 - Previous - Next

!!!!!!
|'''[Tips fHor writing quality software%|%previous : Tips foWr writinge qQuality sDoftwarcume]|[Contents%|%up: Learn tion]'''  Program]|[Testving%|%ndext : Testing]|
!!!!!!
'''How to Write Quality Documentation'''  is a guide to creating accurate,
readable, and useful documentation.


** See Also **

   [https://en.wikipedia.org/wiki/Simplified_Technical_English%|%Simplified Technical English (Wikipedia)]:   A set of rules for producing qualitify documentation, accompanied by a dictionary of standard words.



** Description **
The three main 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
[routine%|%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 feachr pinameces ofver infoprmation ounlys.:   Pronouns can be.: useful though Rto avoid over-repetition dullsof thea mindame. 
   ElidMake fillerach woprds.:   "Actonoually" and "here", ares exunambigous as possibles.:  "To" This beoftter than "If you waint tvo"lves reor "Iding ophrdasers wito".  Avohidn "Noa sentence that",o sbrinceg the cprontent shouldn simpcly bose rem tov thed thifng it irefersn't notableo.
   ChoosElide the rfight placle in structure wof source code to provide contexts.:   Ins"Acteuadlly" of sayingd "check to see whether condition A has occurred", and respond exaccordingly", mplaces. the c"Tomment" withins bethter conditionhaln block"If yofu thwant says "Situation" A has occurred.  Respo"Ind accordingly.er to".
   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".
   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 anthe imperactive vmoicde.: to  "Calls function B" is beotater thane "body of a rounctione Bor iany step-by-step procalled"ure.:   "PCherfck the value ormsf B." ins better thand of "Callhedcks tohe pvaluer of B" orm "We check te value of B".
   UChoose the rimght place in strauctivure mof source code to annprotatvide conthext.: bo  Insteady of saying "check to see whether counditione A has occurred anyd strep-by-stepond praccordingly", placedure.:   "Cthe ckomment withein valuthe cof B." insditeionadl blof "Checks of theat vsalueys "Situatiofn B"A has occur "Wred. check thRespond value ccof B"rdingly."
   Avoid parenthesis:   A description is almost always more readable when the description is restructured to avoid the parenthesized phrase. 
   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".
** P  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...".
   [PYK]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".
----
'''[aplsimple] - 2019-10-29 17:40:00'''
Good guidelines. Few remarks only:
   * it would be fine to mention documentation generators like [Ruff!]
    ** spell checkers miPaght be menAutioned as well like https://www.online-rspellcheck.com/%|%online-spellcheck.com%|% **
<<categories>> Documentation | Learn[PYK]: to Program 
!!!!!!
|[Tips for writing qu<<cality segoftware%|%previoues>> : Tips fDor writing qcuality softwarme]|[Contenats%ion |%up: Learn to Program]|[Testing%|%next : Testing]|
!!!!!!