Simple rules to follow when you write technical docs.
-
Explain stupid things. Do not overestimate reader's understanding. Make you instructions and explanations so straightforward and verbose so your mom could follow them;
-
Do not put periods at the end of headers. "Introduction", not "Introduction.";
-
Let abbreviations to be abbreviations. They should be all uppercased: JSON, FHIR, API, not json, fhir and api;
-
Use capitalized form for product names. Aidbox, not aidbox;
-
Use consistent names for products. Aidbox.Dev, not devbox. Aidbox.Cloud, not "cloud version of Aidbox";
-
Use consistent naming. Introduce term once and then use same name everywhere;
-
If there is a command for some product, use lowercase word to name it. Fhirbase is a HS product, and fhirbase is a command name. Git/git, etc.
-
Use <code> tag for
technical stuff: parameter names, table names, API methods, etc. It allows reader to differentiate computer and human terms; -
Separate commands and their responses into separate <code> blocks. Do not put them into single <code> block. I watched several times how stupid human copies entire code block and pastes it into terminal. Stupid human does not care what's inside, he just copy and paste.
-
Use short sentences.
-
If you're explaining a GUI actions, use screenshots, a lot of them.