The following passage is quoted from: https://diataxis.fr/reference/#writing-a-good-reference-guide
The way a map corresponds to the territory it represents helps us use the former to find our way
through the latter. It should be the same with documentation: the structure of the documentation
should mirror the structure of the product, so that the user can work their way through them
at the same time.
In the case of code, this means arranging the sections of reference documentation to follow the
architecture of the software, where possible.
It doesn't mean forcing the documentation into an unnatural structure. What's important is that the
logical, conceptual arrangement of and relations within the code should help make sense of the
documentation.
Reference material benefits from consistency. Be consistent, in structure, language,
terminology, tone. There are many opportunities in writing to delight your readers with your
extensive vocabulary and command of multiple styles, but reference material is definitely not
one of them.
Technical reference has one job: to describe, and to do that clearly, accurately and
comprehensively. Doing anything else - explaining, discussing, instructing, speculating -
gets in the way of that job, and makes it harder for the reader to find the information they need.
It can be tempting to introduce instruction and explanation, simply because technical reference can
seem too bare. Instead, link to how-to guides, explanation and introductory tutorials as
appropriate.
Examples are valuable ways of providing illustration that helps readers understand reference,
without becoming distracted from the job of describing. For example, an example of usage of a
command can be a succinct way of illustrating it and its context.
These descriptions must be accurate and kept up-to-date. Any discrepancy between the machinery and your description of it will inevitably lead a user astray.
X is an example of y. W needs to be initialised using z. This option does that.
State facts about the machinery and its behaviour.
Sub-commands are: a, b, c, d, e, f.
List commands, options, operations, features, flags, limitations, error messages, etc.
You must use a. You must not apply b unless c. Never d.
Provide warnings where appropriate.