12-rules-of-technical-writing.md

12 Rules of Technical Writing (Concise Reference)

• This concise version is optimized for LLMs and quick reviews.
• Canonical full text: https://strapi.notion.site/12-Rules-of-Technical-Writing-c75e080e6b19432287b3dd61c2c9fa04

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

Quick checklist before review

• Headings meaningful; sections short; sentences concise.
• Numbered steps for procedures; bullets for unordered items.
• Consistent terminology; avoid ambiguity; define acronyms once.
• Include useful visuals when they clarify a concept.
• Wrap commands, file paths, and code identifiers in backticks.