Miscellaneous

Refactor

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

Mood

Prefer the active mood. For example, prefer

Prefer the active mood.

to

The active mood is to be preferred.

The Complete Plain Words

Numbers

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”.

Place names

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

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.

Adjectival phrases

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.

Linking

Take opportunities to link to the Reference, the Knowledge Base, Q for Mortals,etc. Links can start from the site root, e.g. /v2/ref/cond/.

Function reference

In documenting library functions follow the format of the Reference, e.g

.foo.bar (example)

Syntax: .foo.bar[abc;def;ghi;klm]

Where

  • abc is a boolean vector
  • def is blah blah blah
  • ghi is blah blah blah
  • klm is blah blah blah

returns the gorabeezer of hoojamaflip as a table with columns

column semantics
this the first thing
that something like this
other and so on

Narrative, exceptions, errors,tips and and so on.