Refactor your prose as you would your code:
- prefer terser expressions where they do not obstruct readability
- remove duplication, for example, moving repeated phrasing from list items to the list’s preamble
- find ways to simplify expressions
Prefer the active mood. For example, prefer
Prefer the active mood.
The active mood is to be preferred.
Use words for numbers of things, e.g. “there are three ways to achieve this”, up to twenty. Use numbers to refer to numbers themselves, e.g. “and adds 2 to the total”.
Use English place names. Thus Copenhagen not København; Milan not Milano, and Zurich not Zürich.
Using place names correctly in a foreign language is a mark of competence. Using them in English is showing off.
Only is a crucial qualifier in documentation. Place it beside what you intend to qualify.
The reader can usually resolve any ambiguity by eliminating unlikely interpretations. Not always. Placing only in the right place relieves her of this work.
- The function will only return 0 if an error occurs.
If an error occurs, the function will do nothing but return the result of 0. It won’t also set 0 as the value of a variable, write 0 to file…
Here only qualifies return.
- The function will return only 0 if an error occurs.
If an error occurs, the function returns nothing but a solitary zero. Otherwise it may return anything. (Including a zero.)
Here only qualifies 0.
- The function will return 0 only if an error occurs.
If an error occurs the function will return a zero. Otherwise it will return something else.
Here only qualifies if.
Hyphenate adjectival phrases. For example, the hyphen in high-level category indicates that it is the level that is high, not the category. Do this even when there is little or no risk of ambiguity: consistency lightens the reader’s cognitive load.
Take opportunities to link to the Reference, the Knowledge Base, Q for Mortals,etc.
Links can start from the site root, e.g.
In documenting library functions follow the format of the Reference, e.g
abcis a boolean vector
defis blah blah blah
ghiis blah blah blah
klmis blah blah blah
returns the gorabeezer of hoojamaflip as a table with columns
|this||the first thing|
|other||and so on|
Narrative, exceptions, errors,tips and and so on.