Strongly inspired by https://jacobian.org/writing/great-documentation/
When a topic becomes to complicated or complex to be guessed by this documentation's readers, or to improve its current state.
It is convenient to distinct 4 tones to adopt regarding the documentation chapter.
-
Contextualization: Express why you write this documentation, in which context and for who.
This is mainly the purpose of the introduction. -
Step-by-step tutorial: Quick and clear tutorial with cross-references to further in-depth explanations. It should have small steps and frequent "wins" (~every 30 mins) in order to keep the reader in a focus state. It should be easy to follow for the most, but beginners without enough knowledges should fail quickly.
This is mainly the purpose of "Getting started". -
In-depth documentation: Complete explanations of a specific subject or a group of subjects. It should include the range and the goals.
This is mainly the purpose of "Going further". -
Reference: an API or a command-line manual. Examples are welcome.
This is mainly the purpose of "References".
Although it is not easy to choose a writing style, there are some practices that we (are trying to) follow:
-
We - at Cozy - take pleasure to develop and extend Cozy every day, and it should be felt by the reader.
Be enjoyed. -
Adopt a personal tone between you and the reader. Use "you" and the future tense.
Be conversational. -
Don't be afraid to use verb first, to write small sentences and paragraphs, to concatenate ("do not" => "don't"), and to remove unecessary adjectives ("
pretty", "mostly", "good", etc.).
Be concise, forceful and clear. -
Use structural elements liberally: emphasis, lists, notice blocks, images, tables, etc.
Be graphical. -
Find someone to read you before publishing, to avoid writing tics.
Be less French. :-)