docs-strategy

docs-strategy

Authoritative patterns for building and maintaining documentation systems — from single-product READMEs to multi-tenant doc sites, living style guides, and versioned reference portals.

Information Architecture

Define the documentation tree before writing a single page. Group by audience intent, not by your internal team structure.

docs/
├── guides/           # Task-oriented: "How do I...?"
│   ├── quickstart.md
│   ├── authentication.md
│   └── deployment.md
├── reference/        # Lookup: "What does X do exactly?"
│   ├── api/
│   ├── cli/
│   └── config-schema.md
├── concepts/         # Mental models: "Why does this work the way it does?"
│   ├── architecture.md
│   └── data-model.md
├── tutorials/        # Learning-oriented: "Walk me through end-to-end"
│   └── build-your-first-widget.md
└── changelog/        # Temporal: "What changed and when?"
    └── CHANGELOG.md

DITA/Divio quadrant rule: Every page belongs to exactly one quadrant — tutorial, how-to, reference, or explanation. Mixed pages confuse readers and break search ranking.

Style Guide Foundations

Establish these before any other doc work. Retrofit is 10× harder.

# Documentation Style Guide

## Voice and Tone
- Active voice. "Run the command" not "The command should be run."
- Second person. "You configure X" not "The user configures X."
- Present tense. "Returns a 404" not "Will return a 404."

## Naming
- Product name: always "Acme" (never "ACME", "acme", or "the platform")
- Code terms: always backtick-wrapped — `config.yaml`, `run()`, `--flag`
- Files and paths: always backtick-wrapped — `/etc/app/config`

## Code Blocks
- Always specify the language for syntax highlighting
- Include a comment on the first line if context is non-obvious
- Prefer runnable examples over pseudocode

## Callout Types
> **Note:** Supplementary information that may be useful.
> **Warning:** Risk of data loss or breaking change.
> **Tip:** Shortcut or optimization the reader may not know.

## Headings
- H1: page title only (one per page)
- H2: major sections navigated from TOC
- H3: subsections within a section
- Never skip levels (H1 → H3 without H2)