Guidelines for writing documentation and prose: prefer paragraphs over heavy formatting, avoid emojis and decorative elements, use simple and direct language. You should load it when you are writing documentation.
Write in paragraphs first. Reach for bullets or headers only when the content is genuinely list-like or when readers need to scan and jump between sections.
Bad — over-structured, hard to read as a whole:
## Overview
- This tool does X
- It supports Y
- It was built because Z
## Features
- Feature A: does this
- Feature B: does that
Good — flows naturally, easier to absorb:
This tool does X and supports Y. It was built because Z.
It ships with two main features: A, which handles this, and B, which handles that.
Use a list when you have three or more parallel items that don't read well as a sentence. Use a table when you're comparing attributes across multiple things. Use headers when a document is long enough to need navigation.
Bold is for the single most important phrase in a paragraph—the thing a skimmer must not miss. Do not bold for decoration. Do not bold whole sentences.
Use code spans only for actual code: identifiers, commands, file paths. Not for emphasis.
Avoid nested lists. If a list item needs sub-items, the structure is probably too deep—consider rewriting as prose.
Generally avoid them. An occasional emoji in a top-level heading can help a document feel approachable, but that's the limit. Never use emojis in body text, bullet points, or inline callouts.
The more emojis in a document, the less each one means. One is fine. Five is noise.
Write in plain, direct English. Short sentences are better than long ones. One idea per sentence.
Avoid:
Write for someone who is reading quickly. If a sentence can be cut without losing meaning, cut it.
Use callouts sparingly—one or two per document at most. A document full of > **Note:** blocks trains readers to ignore them.
If everything is highlighted, nothing is.