Writing a Style Guide for Your Documentation

Without a style guide, each team member writes docs their own way. One person writes "e.g.", another writes "for example." One uses sentence case for headings, another uses title case. Over time, your docs look like they were written by five different people — because they were.

A style guide is the set of decisions you only want to make once.

What to Include

1. Voice and Tone

markdown
## Voice and Tone

- **Voice:** Direct, helpful, expert.
- **Tone:** Professional but conversational. Not formal, not casual.
- Write to "you" (second person), not "the user."
- Active voice over passive voice.
- Present tense: "The CLI prints a confirmation" not "will print."

2. Formatting Rules

markdown
## Formatting

### Headings
- Sentence case: "Configure your environment" not "Configure Your Environment"
- One H1 per page (the page title)
- Don't skip heading levels

### Bold and Italic
- **Bold** for UI elements, important terms on first use, warnings
- *Italic* for titles of external documents
- No bold for emphasis — rewrite the sentence instead

### Code
- Inline code for: file names, commands, values, parameters, environment variables
- Fenced code blocks for: multi-line code, terminal output, config files
- Always specify the language: ```bash, ```json, ```yaml

3. Terminology Table

markdown
## Terminology

| Use | Avoid | Notes |
|-----|-------|-------|
| **sign in** | log in, login | "Login" is a noun only |
| **dashboard** | admin panel, console | |
| **API key** | API token, secret key | Consistent with UI |

4. UI Elements

markdown
## UI Elements

- **Bold** all UI element names: Click **Save**, open the **Settings** menu
- Use → for navigation paths: **Settings → API → Generate Key**
- Action before location: "Click **Save** in the top-right corner"

5. Code Example Standards

markdown
## Code Examples

- Every code example must be tested and working
- Use realistic values, not "foo" or "test123"
- Use YOUR_API_KEY (all caps) for values readers must replace
- Add a comment explaining any non-obvious line

The Starter Template

markdown
# Documentation Style Guide

## Voice and Tone
## Formatting
### Headings
### Bold and Italic
### Code
## Terminology
## Punctuation
## UI Elements
## Code Examples
## Images and Screenshots
## Accessibility
## Review Process

Enforcing the Style Guide

1. PR templates Add: "[ ] Follows the documentation style guide"

2. Linting Vale is a prose linter that enforces style rules in CI.

3. Ownership Designate one team member as docs reviewer per sprint. Rotate quarterly.

Start Small

If writing a full guide feels overwhelming, start with two things:

1. A terminology table (10 terms, 30 minutes)
2. One formatting rule for code blocks

Add sections as questions arise. The style guide is a living document.

Save this template in MarkGenie and fill it in as your first docs contribution.