'''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 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 Guidelins **
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.
Providefer namesach ovpierce prof infouns.: Prmation ounsly caon bce.: useful though to avoid ovRer-repetition ofdulls athe nameind.
UsElide pronouns to make thfings morller cwoncirdse.: and na "Actural:ly" This doesn't contrandict t"he previous", arue examples. Ra"To" is bethter theyan sh"If yould bowanth be applied to" achieveor a"In goord senr tenceo".
MakChoose theac right prolace inoun as trunambigcture ousf asource code to prossviblde context.: ThiInstead often sayinvolvg "check to see rwheother conditiong pA hras occurred and respond waccordithingly", pla scen then comme nto brwithing the prconditiounal cbloserck tof theat says "Sithuationg itA has occurrefd. Rerspond taccordingly."
ElidPre filler worda s.:equence of short "Alogictually" statemendts "hover longe",r amore examplrosaic descriptions.: "To" is bMentteral thspance "Ifis you want to"a opr "In order to"mium.
UsPre thfer preosenitive terminseology.: "ProducIt is easier and more memorabliste tof build a mental modes"l isof bewhat a systerm does than "Wof what illt prdoesn't do. "Ensucre that" lis better of than "amesvoid".
PrUsefer singular fshorm.: "Ensurtesr tphrat thse indicatedf cached item is jup-st as info-drmative", isor bsufficiently informativer.: than "EThe onsuly reason thato cachedo A" might bems are up-to-dlatce".d with H"Dow A bevcauser, plural...". form is s"Nometimes the beatter choiceA fdor rules" cand constbe replaced wints:h "IA doentifiers beginning...". with aIn punctuartion mculark, arvoid the resdundant "The rvedason for A isystem because...".
ElFinde the subjecright word.: "PUse produecise terms a linstead of nparaphrasing, choose mores" specific words bovettr more general thwords, and "Tuse thie most fundirecti wonrd or phroducease. a"When" lis better of than "any times".
Use Explain twhird-party pbeforspec stative ing summwhariest.: "PThe resodurce doesn't exist, so set the variable to Faliste." is better than "PSet the variable tod false because the resource adoesn't lexist"."
UsAvoid the an bstractive voice.: "CallWords futhat encd in "ness", "tion B", "ism", better thand "funcity" ion B dis callted". "Poverforly-academic phrasing. B" Instead, find a way to say bethater somethaing "Called to perfs or is something B"else.
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".
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."
** Grammar Guidelines **
Prefer a sequence of short logical statements over longer more prosaic descriptions.: Mental space is at a premium.
Prefer ponamesiti over teprmionologyuns.: It is easiePr aond moreuns memorcan ble to build a msentaful mthodel of wughat a system does than vof what it doesn't do. "Ensuver-re pethait" ison betterof than "navoid"me.
Use a shorter phraonounse if ito is just maske thinfgs mormative, cor suffincise antlyd informative.ural: "Theis donly reason 'to dco A" mighnt be replaced wict the "Do A bprecaviouse rule...". "NoRather that A does"y can be repshoulaced wiboth "A dobes ...". In particupplar, avoied theo redundant "Tchie rve ason fgorod A is bentencause...".
FindMake theach pronoun as unambightuous was pordssible.: Use precThise oftermsn instvolveads reof paraphrasding, cphoose more aspecs wifthicn wordsa ovser mornte genceral wtords, abrindg use the mprostnoun direct wloserd tor pthrase. "Wthein"g ist brettfers than "any time"o.
ExplainUse wthy befo pre statiengt whatense.: "The Presodurce doesn't exa list, sof set the vnariablme to False." is better than "Set the varWiable to false because the presodurce doea lisn't of namexist.".
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".
AvoElide the abstraubject.: Wo"Produces tha list endof in "namess", "tion", "ism", and "ibety" arter good cthand "Thidates. Instead, fiund a way cto say that somethiong dproduces ora list sof namething else".
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".
Avoid parenthesis: A description is almost always more readable when the description is restructured to avoid the parenthesized phrase.
** Page Authors **
[PYK]:
----
'''[aplsimple] - 2019-10-29 17:40:00'''
Good guidelines. Few remarks only:
* it would be fine to mention documentation generators like [Ruff!]
* spell checkers might be mentioned as well like https://www.online-spellcheck.com/%|%online-spellcheck.com%|%
<<categories>> Documentation | Learn to Program