<aside> 👋 Rules and guidelines to follow when writing technical documentation. DRI: @Mégane Lacheny, @Pierre Wizla Last update: April 2025

</aside>

<aside> <img src="/icons/safety-pin_gray.svg" alt="/icons/safety-pin_gray.svg" width="40px" /> TL;DR — 12 Rules of Technical Writing

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 pronouns too much.
12. Don't overuse capital letters and bold: use proper content formatting instead (see style guide).

</aside>

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.

<aside> 📝 - 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.

</aside>

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 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.

<aside> 📝 - 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.

</aside>