12 Rules of Technical Writing

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.