DOCUMENTATION_STYLE_GUIDE.md

Documentation Style Guide

A generic style guide for writing clear, maintainable technical documentation. Use it as a baseline for project READMEs, guides, references, runbooks, architecture notes, and API documentation.

Table of Contents

• Quick Reference
• Core Principles
• Document Types
• Document Structure
• Writing Style
• Formatting Standards
• Code and Command Examples
• Diagrams and Visuals
• API Documentation
• File Organization
• Maintenance
• Review Checklist
• Templates

Quick Reference

Essential Rules

• Write for the reader's task, not the author's implementation details
• Start every document with a clear H1 title and a short summary
• Include a table of contents for long documents or documents with many sections
• Use active voice, direct language, and consistent terminology
• Specify a language for every fenced code block
• Prefer copy-paste-friendly commands without shell prompts
• Test examples before publishing when practical
• Use Mermaid for architecture, flow, sequence, state, and relationship diagrams
• Use text trees for directory structures and terminal-style blocks for transcripts
• Avoid line numbers in durable file references unless tied to a specific commit or ephemeral review
• Avoid duplicating dependency versions already defined in package manifests
• Update related links, examples, and references when changing documentation

Prefer This

The `createClient()` function reads configuration from `config.yaml`.

```bash
example-cli validate config.yaml
```

Avoid This

The functionality located at `src/client.ts:184` should be utilized by users.

```bash
$ example-cli validate config.yaml
```

Use shell prompts only for interactive transcripts, not for commands intended to be copied.

Core Principles

Principle	Guidance
Clarity	Say exactly what the reader needs to know or do
Accuracy	Keep examples, links, and behavior aligned with the current implementation
Scannability	Use headings, lists, tables, and examples to support quick reading
Maintainability	Avoid brittle details such as line numbers, duplicated versions, and stale screenshots
Consistency	Use the same names, terms, capitalization, and structure across related docs
Accessibility	Do not rely on color alone; provide labels, descriptions, and readable contrast

Document Types

Different documents need different structures. Do not force every document into the same template.

Type	Purpose	Recommended Sections
README	Orient new users and contributors	Purpose, install/setup, quick usage, development, links
Quickstart	Help users succeed quickly	Prerequisites, steps, verification, next steps
How-to guide	Complete a specific task	Goal, prerequisites, steps, troubleshooting, verification
Reference	Provide complete facts/options	Scope, concepts, options/API, examples, related docs
Architecture note	Explain design and tradeoffs	Context, goals, components, data/control flow, tradeoffs, risks
Runbook	Operate or recover a system	Symptoms, impact, diagnosis, remediation, rollback, escalation
Troubleshooting	Resolve known issues	Symptoms, likely causes, fixes, verification
Migration guide	Move between versions or systems	Audience, breaking changes, preparation, steps, rollback, validation
Changelog/release notes	Record released changes	Version/date, added/changed/fixed/removed, migration notes

Document Structure

Required Baseline

Every durable documentation file should include:

1. Title (H1): One clear document title
2. Summary: One or two sentences explaining scope and audience
3. Main content: Sections organized by reader workflow
4. Related links: Relevant follow-up docs when useful

Longer documents should also include:

• Table of contents: For documents over roughly 500 words or with more than three major sections
• Prerequisites: For procedural docs that assume tools, access, or background knowledge
• Verification: For setup, operations, and troubleshooting docs
• Troubleshooting: For workflows with common failure modes

Heading Hierarchy

Level	Use	Example
H1	Document title only	# Deployment Guide
H2	Major sections	## Configure the Service
H3	Subsections	### Environment Variables
H4	Small divisions inside complex sections	#### Retry Behavior
H5+	Avoid when possible	Prefer lists or split the section

Recommended Information Flow

graph TD
    Title[Title]
    Summary[Summary]
    Context[Context or Overview]
    Prereq[Prerequisites]
    Body[Main Content]
    Examples[Examples]
    Verify[Verification]
    Trouble[Troubleshooting]
    Related[Related Documentation]

    Title --> Summary
    Summary --> Context
    Context --> Prereq
    Prereq --> Body
    Body --> Examples
    Examples --> Verify
    Verify --> Trouble
    Trouble --> Related

    class Title primary
    class Summary,Context info
    class Prereq warning
    class Body,Examples active
    class Verify success
    class Trouble error
    class Related neutral

    classDef primary fill:#e65100,stroke:#ff9800,stroke-width:3px,color:#ffffff
    classDef active fill:#1b5e20,stroke:#4caf50,stroke-width:2px,color:#ffffff
    classDef success fill:#2e7d32,stroke:#66bb6a,stroke-width:2px,color:#ffffff
    classDef error fill:#b71c1c,stroke:#f44336,stroke-width:2px,color:#ffffff
    classDef warning fill:#ff6f00,stroke:#ffa726,stroke-width:2px,color:#ffffff
    classDef info fill:#0d47a1,stroke:#2196f3,stroke-width:2px,color:#ffffff
    classDef neutral fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff

Loading

Writing Style

Voice and Tone

• Direct: Tell readers what to do and what happens next
• Professional: Be precise without sounding bureaucratic
• Approachable: Explain unfamiliar concepts before using shorthand
• Inclusive: Avoid assumptions about the reader's background, location, or tooling
• Current: Use present tense for current behavior

Style Rules

Do	Avoid
“Run the command to validate the configuration.”	“The command should be executed in order to validate the configuration.”
“The API returns JSON.”	“JSON is returned by the API.”
“Set timeoutSeconds to 30.”	“Set an appropriate timeout value.”
“Use repository, not repo, in this file.”	Mixing “repository”, “repo”, and “project” for the same concept

Terminology

• Define acronyms on first use: “Application Programming Interface (API)”
• Prefer one canonical term for each concept
• Use product, command, and package names exactly as they appear in the project
• Avoid jokes, idioms, or culture-specific phrases in technical instructions

Procedural Writing

For step-by-step instructions:

1. Start each step with an action verb
2. Include only one primary action per step
3. Explain why when the reason affects user choice or safety
4. Show expected output or success criteria when useful
5. End with verification

Formatting Standards

Inline Formatting

Element	Format	Example
File paths	Backticks	src/config.ts
Commands	Backticks or fenced blocks	example-cli init
Function/class names	Backticks	createClient()
Environment variables	Backticks	API_KEY
UI labels	Bold or quoted consistently	Save
Emphasis	Bold sparingly	Important:

File References

Avoid line numbers in durable documentation because they become stale after edits.

Good:

• “See src/client.ts for the client implementation.”
• “The createClient() function validates the options object.”
• “The deployment workflow lives in .github/workflows/deploy.yml.”

Avoid:

• “See src/client.ts:184.”
• “Update lines 20-45 in config.ts.”
• “The bug is fixed at /Users/example/project/src/client.ts:184.”

Line numbers are acceptable in temporary debugging notes, issue comments, or review comments tied to a specific commit SHA.

They are also acceptable when the path:line string is the subject of the documentation rather than a reference to a real file. Features that recognize file:line text — semantic history, path detection, error-output parsing — must show that syntax to explain what they match, and rewriting those examples as symbol names would document the wrong thing.

Version References

Avoid duplicating dependency or package versions in general documentation. Version numbers drift and should usually live in package manifests, lockfiles, release notes, or generated API references.

Good:

• “See the project manifest for dependency versions.”
• “Requires the runtime version specified by the project configuration.”
• “Use the version documented in the package manifest.”

Acceptable places for versions:

• Changelogs and release notes
• Migration guides
• Compatibility matrices
• Security advisories
• Troubleshooting notes for version-specific bugs
• Package manifests and lockfiles

Callouts

Use blockquotes for important contextual notes. Keep them short.

Note: Additional context that helps understanding.

Tip: A helpful shortcut or best practice.

Warning: A risk that can cause data loss, downtime, or confusing behavior.

Security: Information related to secrets, permissions, data exposure, or trust boundaries.

Deprecated: A feature or approach that should no longer be used.

Code and Command Examples

Code Blocks

Always specify a language for fenced code blocks.

```ts
export interface ClientOptions {
  endpoint: string;
  timeoutSeconds?: number;
}
```

Use comments to explain why code is written a certain way, not to restate obvious operations.

const cacheTtlSeconds = 300; // Balances freshness with upstream rate limits.

Commands

Use copy-paste-friendly commands without a prompt when the reader should run them directly.

example-cli validate config.yaml
example-cli deploy --dry-run

Use prompts only for transcripts or interactive sessions.

$ example-cli status
Service: healthy
Queue: empty

Expected Output

Include output when it helps readers confirm success. Keep long output abbreviated.

example-cli test

✓ Configuration loaded
✓ Connection established
✓ Checks passed

Secrets and Credentials

• Never include real API keys, tokens, passwords, private keys, or connection strings
• Use placeholders such as <API_KEY> or example-token
• Make clear where secrets should be stored
• Warn when a workflow crosses a trust boundary, such as browser-to-server credentials

Error Examples

Show the symptom, cause, fix, and verification.

#### Error: `Permission denied`

**Symptom:** The command exits with `Permission denied`.

**Likely cause:** The current user cannot read the configuration file.

**Fix:** Update file ownership or run the command with the correct user.

```bash
example-cli validate config.yaml
```

**Verify:** The command exits successfully and prints `Configuration valid`.

Diagrams and Visuals

When to Use Mermaid

Use Mermaid for:

• Architecture diagrams
• Flow charts
• Sequence diagrams
• State diagrams
• Entity relationship diagrams
• Dependency diagrams

Use text blocks for:

• Directory trees
• Terminal transcripts
• Simple before/after file layouts

Mermaid Style

Prefer classDef styles over repeated per-node style declarations.

graph TD
    Client[Client]
    API[API]
    DB[(Database)]

    Client --> API
    API --> DB

    class Client external
    class API primary
    class DB database

    classDef primary fill:#e65100,stroke:#ff9800,stroke-width:3px,color:#ffffff
    classDef database fill:#1a237e,stroke:#3f51b5,stroke-width:2px,color:#ffffff
    classDef external fill:#4a148c,stroke:#9c27b0,stroke-width:2px,color:#ffffff

Loading

Diagram Color Palette

Use high-contrast colors and clear labels. Do not rely on color alone to convey meaning.

Semantic Role	Fill	Stroke	Use
Primary	#e65100	#ff9800	Main service or orchestration point
Active/Healthy	#1b5e20	#4caf50	Healthy components or active paths
Success	#2e7d32	#66bb6a	Successful states or completed operations
Error/Failed	#b71c1c	#f44336	Failures or unavailable components
Warning	#ff6f00	#ffa726	Risk, decision, or caution points
Data/Storage	#0d47a1	#2196f3	Caches, queues, or data services
Database	#1a237e	#3f51b5	Persistent storage
External/Client	#4a148c	#9c27b0	Users, clients, external systems
Neutral/Info	#37474f	#78909c	Notes, inactive components, or metadata

Accessibility

• Label states and arrows clearly
• Add a short explanation before or after complex diagrams
• Provide alt text or captions for images
• Avoid tiny text in screenshots
• Prefer diagrams that remain readable in light and dark themes

API Documentation

Endpoint Template

### Create Resource

Creates a resource and returns the created representation.

**Method:** `POST`
**Path:** `/api/resources`
**Authentication:** Required

#### Request Headers

| Header | Required | Description |
| --- | --- | --- |
| `Authorization` | Yes | Bearer token |
| `Content-Type` | Yes | `application/json` |

#### Request Body

```json
{
  "name": "example",
  "enabled": true
}
```

#### Success Response

**Status:** `201 Created`

```json
{
  "id": "resource_123",
  "name": "example",
  "enabled": true
}
```

#### Error Responses

| Status | Cause | Response |
| --- | --- | --- |
| `400 Bad Request` | Invalid input | Validation error details |
| `401 Unauthorized` | Missing or invalid credentials | Authentication error |
| `409 Conflict` | Resource already exists | Conflict error |

#### Example

```bash
curl -X POST https://api.example.com/resources \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"example","enabled":true}'
```

API Reference Guidelines

• Document authentication and authorization requirements
• List path, query, header, and body parameters separately
• Include data types, required status, defaults, and constraints
• Show success and common error responses
• Include idempotency, pagination, rate limit, and retry behavior when relevant
• Keep examples safe: no real credentials or production identifiers

File Organization

Common Documentation Layout

docs/
├── README.md
├── DOCUMENTATION_STYLE_GUIDE.md
├── architecture/
│   └── system-overview.md
├── guides/
│   └── deployment.md
├── reference/
│   └── configuration.md
├── runbooks/
│   └── service-recovery.md
└── troubleshooting/
    └── common-errors.md

Directory trees are allowed even though they use text characters; they are not a substitute for architecture or flow diagrams.

Naming Conventions

Choose one naming convention per project and use it consistently.

Common options:

Convention	Example	Notes
Lowercase kebab-case	deployment-guide.md	Good for web docs and static site generators
Upper snake case	DEPLOYMENT_GUIDE.md	Common in repo-root docs
Conventional root names	README.md, CONTRIBUTING.md	Use established ecosystem names

Avoid renaming existing documentation solely for style unless the project is already doing a documentation reorganization.

Maintenance

Documentation Lifecycle

graph LR
    Draft[Draft or Update]
    Review[Review]
    Test[Test Examples]
    Publish[Publish]
    Monitor[Monitor for Drift]
    Revise[Revise]

    Draft --> Review
    Review --> Test
    Test --> Publish
    Publish --> Monitor
    Monitor --> Revise
    Revise --> Review

    class Draft active
    class Review info
    class Test warning
    class Publish primary
    class Monitor neutral
    class Revise active

    classDef primary fill:#e65100,stroke:#ff9800,stroke-width:3px,color:#ffffff
    classDef active fill:#1b5e20,stroke:#4caf50,stroke-width:2px,color:#ffffff
    classDef warning fill:#ff6f00,stroke:#ffa726,stroke-width:2px,color:#ffffff
    classDef info fill:#0d47a1,stroke:#2196f3,stroke-width:2px,color:#ffffff
    classDef neutral fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff

Loading

Update Checklist

When changing documentation:

1. Check whether linked docs also need updates
2. Update internal anchors if headings changed
3. Verify examples still match the implementation
4. Remove stale screenshots, diagrams, and references
5. Run available documentation checks
6. Add release notes or changelog entries when the change affects users

Recommended Automated Checks

Use whichever tools fit the project:

• Markdown linting
• Link validation
• Spell checking or terminology checks
• Code block extraction and testing
• Mermaid rendering validation
• API reference generation or schema validation

Review Checklist

Structure

• One H1 title
• Clear summary near the top
• Table of contents when useful
• Headings follow a logical hierarchy
• Related links are present when helpful

Content

• The intended audience is clear
• The document answers the reader's likely task or question
• Terms are defined and used consistently
• Assumptions and prerequisites are explicit
• Safety, security, and rollback notes are included where relevant

Examples

• Code blocks specify languages
• Commands are copy-paste friendly unless shown as transcripts
• Examples use placeholders instead of real secrets
• Expected output or verification is included when useful
• Examples have been tested or clearly marked as illustrative

Links and Maintenance

• Internal links and anchors work
• External links are still valid
• File references avoid brittle line numbers
• Version references are necessary and maintainable
• Related docs and changelogs are updated when needed

Visuals

• Mermaid is used for diagrams where appropriate
• Directory trees are formatted as text
• Diagrams include clear labels and do not rely on color alone
• Images have alt text or nearby descriptions

Templates

General Guide Template

# Guide Title

One or two sentences describing what this guide helps the reader accomplish.

## Table of Contents

- [Overview](#overview)
- [Prerequisites](#prerequisites)
- [Steps](#steps)
- [Verify](#verify)
- [Troubleshooting](#troubleshooting)
- [Related Documentation](#related-documentation)

## Overview

Explain the goal, scope, and expected outcome.

## Prerequisites

- Required access
- Required tools
- Required configuration

## Steps

1. **Do the first action**

   ```bash
   example-cli prepare
   ```

2. **Do the second action**

   ```bash
   example-cli apply
   ```

## Verify

```bash
example-cli status
```

Expected result: the command reports a healthy status.

## Troubleshooting

### Problem: Brief symptom

**Cause:** Likely cause.

**Fix:** Corrective action.

**Verify:** How to confirm the fix worked.

## Related Documentation

- [Related topic](related-topic.md) - Why it is useful

Architecture Note Template

# Architecture: System or Feature Name

Brief summary of the design and why it exists.

## Context

What problem this design addresses and what constraints shaped it.

## Goals

- Goal one
- Goal two

## Non-Goals

- Explicitly out-of-scope item

## Components

```mermaid
graph TD
    Client[Client]
    Service[Service]
    Store[(Store)]

    Client --> Service
    Service --> Store
```

## Data Flow

Describe how data or control moves through the system.

## Tradeoffs

| Choice | Benefit | Cost |
| --- | --- | --- |
| Selected approach | Why it helps | What it makes harder |

## Operational Notes

Monitoring, deployment, rollback, and failure-mode considerations.

## Related Documentation

- [Related guide](related-guide.md)

Troubleshooting Template

# Troubleshooting: Problem Area

Use this guide to diagnose and resolve common problems with the system or workflow.

## Symptom: Brief Description

**Impact:** What the user or system experiences.

**Likely causes:**

- Cause one
- Cause two

**Diagnosis:**

```bash
example-cli diagnose
```

**Fix:**

```bash
example-cli repair
```

**Verify:**

```bash
example-cli status
```

Expected result: the status is healthy.

**Escalate if:** Conditions that require additional help.