doc-style

name	doc-style
description	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.

Documentation Style

Prefer prose over structure

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.

Keep formatting minimal

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.

Emojis

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.

Language

Write in plain, direct English. Short sentences are better than long ones. One idea per sentence.

Avoid:

• Filler openers: "In order to", "It is worth noting that", "As mentioned above"
• Passive voice when the actor matters: "The file is created by the CLI" → "The CLI creates the file"
• Vague intensifiers: "very", "quite", "really", "basically"
• Inflated vocabulary when a plain word works: "utilize" → "use", "facilitate" → "help", "implement" → "add" or "build"

Write for someone who is reading quickly. If a sentence can be cut without losing meaning, cut it.

Callouts and warnings

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.