Rules and guidelines to follow when writing technical documentation. DRI: @Mégane Lacheny, @Pierre Wizla Last update: September 2021
TL;DR 1. Remember your audience but don't assume anything: document the obvious. 2. Don't try reinventing the wheel: what you write must blend in, never step out. 3. Adopt a direct and neutral tone: no jokes, no random emojis, no funny GIFs. 4. Stick to simple English: one shouldn't need a dictionary to understand documentation. 5. Write concise, straight-to-the-point content with short sentences separated into sections. 6. Never say something is "easy" or "difficult". 7. Make sure your directions are displayed in numbered lists. Remember: one step = one action. 8. Replace enumerations with bullet lists and complex lists with tables. 9. Keep away from ambiguous pronouns and abbreviations, and use acronyms sparingly. 10. Take advantage of the power of illustrations: screenshots and schemas are sometimes better than long sentences. 11. Avoid using "you" too much. The same goes with "we". 12. Don't overuse capital letters and bold: use proper content formatting instead (see style guide).
01. Remember your audience but don't assume anything
The level of technicality varies from one documentation to another, depending on the targeted audience. Although the latter should be taken into consideration, remember that nothing is obvious for everyone. Do not assume all readers have the same knowledge on a topic as you do.
- Mention even the most basic requirements needed to follow a procedure. - Precise exactly the admin panel section or file/folder in which the reader should be. - Use introductions to your advantage to define concepts mentioned in the rest of the documentation.
02. Don't try reinventing the wheel
Technical writing is all about following rules and guidelines and keeping everything homogeneous. Our documentation should be thought as a whole, each part of it being consistent with the others. No documentation file should give the impression that it was written by several different people, and no documentation section should clearly step out from the others.
👉 Follow the Strapi documentation style guide.
03. Adopt a direct and neutral tone
When writing documentation, focus on clear and understandable content. Readers generally turn to documentation to acquire new knowledge or get answers about an issue they encountered. They shouldn't read specific opinions or funny jokes, but only find direct information documented in a neutral manner. Keep the jokes, friendly tone, random emojis and funny gifs for other types of content. The same goes for opinionated types of content: technical documentation is not the place for that.
04. Stick to simple English
Unlike original technical writing used in fields like aviation, we do not use Simplified Technical English. However, we still aim at providing documentation that is as easy to understand as possible. Do not try to showcase your best literary English. Use simple words, keep away from synonyms and avoid fancy turns of phrase. Keep in mind that not all readers are native English speakers, and they shouldn't need a dictionary to understand documentation.
05. Write concise, straight-to-the point content
Although the content is the most important aspect of a documentation, its visual aspect does matter also. The documentation shouldn't appear as one block of text - this isn't appealing for anyone and its makes it much harder to find specific information. Emphasise the content and make it digestible by writing short sentences, and break down the whole content in readable and coherent separate sections.
- Avoid transitional words (e.g. furthermore, moreover, consequently, etc.). - Get immediately to the point to explain: there is no need for long introductory paragraphs. - Take advantage of the content formatting options to separate autonomous kind of information from the main content (see style guide). - Write numbers as numerals instead of spelling them out, as it is visually easier to read. - Avoid parenthesis as they break the sentence for generally lesser important information; keep them only for full form of acronyms and short examples.
06. Never say something is "easy" or "difficult"
Keep in mind that what you find easy may not feel the same for someone else. If a reader struggles to understand some part of the documentation that was explicitly defined as "easy" or "simple", they could feel like they're not good enough. Similarly, writing that something is "difficult" may discourage a reader who could feel like they are not ready or skilled enough. Create a documentation that is easy-to-understand for as many readers as possible.
07. Make sure your directions are displayed in numbered lists
A series of directions that the reader should follow in the right order is called a procedure. It must always be displayed in a numbered list. Every step of the list should only contain one action — optionally also a result (e.g. a window opens, with which the reader will interact for the rest of the procedure). Make sure your procedures focus on the action. Start procedures steps with an action verb to ensure that the readers immediately know what they should do.
08. Replace enumerations with bullet lists
Listing items is common in technical writing (e.g. features available from an interface, actions that can be performed and are documented together, etc.). Instead of enumerating items in a long paragraph, display them in a bullet list. Similarly, complex lists of items (more than 10 items and/or items that need additional explanations) should be displayed in a table. Bullet lists and tables are more visual and help reading and understanding content more easily.
09. Keep away from ambiguity and unclarity
Technical documentation should be clear and precise: any form of ambiguity or unclarity should be avoided, to make sure there is no place for misunderstanding when reading the content.
- Avoid jargon and abbreviations as they are not always internationally known and understood. - Use acronyms sparingly - but if you do, make sure their full meaning is stated at least one time in the page (e.g. "Respect the DRY (Don't Repeat Yourself) concept"). - Features, concepts and actions should always be designated by the same word: do not bother looking for synonyms, we are not afraid of repeating the same word in technical writing.
10. Take advantage of the power of illustrations
Illustrations can be worth many words. They can completely replace textual content (e.g. schema) or add up to textual content to make explanations clearer or more precise (e.g. screenshot). If you are unsure of an explanation you wrote, or tackle a topic that is rather complex and/or related to others, do remember illustrations can be helpful.
👉 Check the Strapi documentation style guide about illustrations.
- Screenshots can be annotated to help the reader know exactly what the situation should be like. - Schemas remain the best tool to visually show an architecture or infrastructure of some kind. - GIFs (although to be used sparingly) can be a great way to show a series of actions without bothering the reader with a video.
11. Avoid using "you" too much
The Strapi documentation is not addressed to someone in particular, and it is neither about "you" or "we". Avoid those to make the documentation as general as possible. Getting rid of unnecessary pronouns allows the reader to focus more on the action or explanation itself, and it is also an efficient way to reduce the size of sentences, hence writing concise content.
12. Don't overuse capital letters and bold
Text highlights, such as bold and italics, should be reserved for specific words (see style guide) and keep their purpose throughout the whole documentation. In particular, whole sentences should never be in bold. If a piece of information is highly important, it should be shown in the way it is written and displayed with the rest of the content (e.g. displayed as a special notice in a callout, or in its own paragraph). The same goes with capital letters: never write whole words or sentences in capital letters.