Documentation Style Guide

Apply these principles when writing or reviewing documentation to ensure clarity, consistency, and accessibility for both human readers and LLMs.

Voice and Tone

Use Second Person

Address the reader directly as "you" rather than "the user" or "developers."

CODEBLOCK0

Prefer Active Voice

Write sentences where the subject performs the action. Active voice is clearer and more direct.

CODEBLOCK1

Be Concise

Cut unnecessary words. Every word should earn its place.

CODEBLOCK2

CODEBLOCK3

Common phrases to simplify:

Instead of	Use
in order to	to
for the purpose of

to, for |
| in the event that | if |
| at this point in time | now |
| due to the fact that | because |
| it is necessary to | you must |
| is able to | can |
| make use of | use |

Document Structure

Write Clear, Descriptive Headings

Headings should tell readers exactly what the section contains. Avoid clever or vague titles.

CODEBLOCK4

Create Self-Contained Pages

Assume readers may land on any page directly from search. Each page should:

• - Explain what the feature/concept is
• State prerequisites clearly
• Provide complete context for the topic

CODEBLOCK5

Use Semantic Markup

Choose the right format for the content type:

• - Headings: Follow proper hierarchy (h1 > h2 > h3, never skip levels)
• Lists: Use for multiple related items
• Tables: Use for structured data with consistent attributes
• Code blocks: Use for any code, commands, or file paths

CODEBLOCK6

Make Content Skimmable

Break dense paragraphs into digestible chunks:

• - Keep paragraphs to 3-4 sentences maximum
• Use bullet points for lists of items
• Add subheadings to long sections
• Put key information first (inverted pyramid)

CODEBLOCK7

Consistency

Use One Term Per Concept

Pick a term and use it consistently. Switching terms confuses readers.

CODEBLOCK8

Document your terminology choices:

Concept	Use	Don't use
Authentication credential	API key	API token, secret key, access key
Configuration file

config file | settings file, preferences file |
| Command line | CLI | terminal, command prompt, shell |

Apply Consistent Formatting

Use the same formatting for similar content types:

• - UI elements: Bold (Click Save)
• Code/commands: Backticks (npm install)
• File paths: Backticks (/etc/config.yaml)
• Key terms on first use: Bold or italics
• Placeholders: SCREAMING_CASE or angle brackets (YOUR_API_KEY or <api-key>)

LLM-Friendly Patterns

State Prerequisites Explicitly

List what users need before starting. This helps both humans and LLMs understand context.

CODEBLOCK9

Define Acronyms on First Use

Spell out acronyms the first time they appear on a page.

CODEBLOCK10

Provide Complete, Runnable Code Examples

Code examples should work when copied. Include:

• - All necessary imports
• Realistic placeholder values
• Expected output (when helpful)

CODEBLOCK11python
import requests

API_KEY = "your-api-key"
BASE_URL = "https://api.example.com/v1"

response = requests.get(
f"{BASE_URL}/users",
headers={"Authorization": f"Bearer {API_KEY}"}
)

print(response.json())

Output: {"users": [{"id": 1, "name": "Alice"}, ...]}

<!-- Avoid: Incomplete snippet -->

python
response = requests.get(url, headers=headers)
CODEBLOCK13

Write Descriptive Titles and Meta Descriptions

Page titles and descriptions help with search and LLM understanding.

CODEBLOCK14

Pitfalls to Avoid

Don't Use Product-Centric Language

Orient documentation around user goals, not product features.

CODEBLOCK15

Skip Obvious Instructions

Don't document self-explanatory UI actions.

CODEBLOCK16

Avoid Colloquialisms

Colloquialisms hurt clarity and localization.

CODEBLOCK17

Quick Reference Checklist

When writing documentation, verify:

• - [ ] Using "you" instead of "the user"
• [ ] Active voice throughout
• [ ] No unnecessary words
• [ ] Headings are descriptive
• [ ] Page is self-contained
• [ ] Proper heading hierarchy
• [ ] One term per concept
• [ ] Prerequisites listed
• [ ] Acronyms defined
• [ ] Code examples are complete
• [ ] No product-centric language
• [ ] No colloquialisms

Applying This Skill

Use these principles when:

1. 1. Writing new documentation: Apply all principles from the start
2. Reviewing documentation: Check against the quick reference checklist
3. Editing existing docs: Prioritize voice/tone, then structure, then consistency
4. Creating code examples: Ensure they are complete and runnable