# Docs Architecture

> Structure and write project documentation beyond the README. Use when docs have sprawled into an unnavigable pile, when users keep asking questions the docs already answer, when choosing a docs site generator (Docusaurus, MkDocs, VitePress, mdBook, Sphinx), or when planning a docs information architecture. Covers the Diataxis framework (tutorial/how-to/reference/explanation), versioning docs across releases, API reference generation, doc testing, and migration guides. Also use for "write docs for this project" or "our docs are bad".

- Skill: `the-open-agent/docs-architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add the-open-agent/docs-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/the-open-agent/docs-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: the-open-agent (https://skillmd.com/u/the-open-agent)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/the-open-agent/docs-architecture

---


# Documentation Architecture

Most bad documentation is not badly written — it is badly *sorted*. A tutorial with
reference material interleaved fails at both jobs. Fix the structure first; the prose
problem usually dissolves.

## Diátaxis: the four modes

Every documentation page serves exactly one of four purposes. Mixing them is the root
cause of most docs complaints.

| | **Learning** (study) | **Working** (doing) |
|---|---|---|
| **Practical steps** | **Tutorial** — a guided first success | **How-to** — a recipe for a specific goal |
| **Theoretical knowledge** | **Explanation** — why it works this way | **Reference** — exhaustive, dry, accurate |

- **Tutorial** — "Build your first X in 10 minutes." One path, no choices, guaranteed
  to work. The reader is a beginner; every decision you offer them is a chance to
  fail. Optimize for *finishing*, not for teaching everything.
- **How-to** — "How to deploy behind a proxy." Assumes competence. Starts at a goal,
  ends at the goal. Titled `How to <verb> <object>` so search finds it.
- **Reference** — the API, the CLI flags, the config schema. Complete, consistent,
  boring. Generated from source wherever possible. No teaching, no opinions.
- **Explanation** — "Why we use content-addressed storage." Read in an armchair, not
  at a keyboard. This is where design rationale, tradeoffs, and history belong.

Diagnostic: pick any page and name its quadrant. If you cannot, that page is the
problem. Common failure — a "Getting Started" page that is 30% tutorial, 50% reference
and 20% explanation, so a beginner drowns and an expert cannot find the flag list.

Minimum viable docs, in order of when to add them:

1. README (see `readme-that-converts`)
2. One tutorial — the 10-minute first success
3. Reference — generated
4. How-tos — one per recurring support question, written *when* it recurs
5. Explanations — when "why is it like this?" gets asked twice

## Let the issue tracker write your docs

The highest-leverage docs process there is: every question answered more than once
becomes a how-to page.

```bash
gh issue list --state all --limit 200 --json title,labels,comments \
  --jq '.[] | select(.labels[]?.name == "question") | .title'
```

Cluster the results. Each cluster of three or more is a missing page. Then close
future duplicates with a link — and if you find yourself linking the same page while
also explaining it, the page is not doing its job yet.

## Choosing a generator

| Tool | Best for | Cost |
|---|---|---|
| **MkDocs + Material** | Python projects, fast start, excellent defaults | Python toolchain |
| **Docusaurus** | JS/TS ecosystems, versioned docs, i18n, React embeds | Node build, heavier |
| **VitePress** | Lightweight, fast builds, Vue-adjacent | Fewer batteries |
| **mdBook** | Rust projects, books, minimal deps | Limited plugins |
| **Sphinx** | Scientific Python, deep autodoc, cross-refs | Steepest learning curve |
| **Just `docs/*.md`** | Under ~10 pages | No search, no versioning |

Do not build a docs site before you have ~10 pages. Markdown in `docs/` renders fine
on GitHub and costs nothing to maintain. The site is a response to scale, not a
prerequisite for it.

Whatever you pick: **deploy on merge to main**, from CI, to GitHub Pages or similar.
Docs that require a human to publish are docs that go stale.

## Reference docs must be generated

Hand-written API reference drifts within weeks. Generate from the source of truth:

```bash
typedoc --out docs/api src/index.ts       # TypeScript
sphinx-apidoc -o docs/api src/            # Python (or mkdocstrings)
cargo doc --no-deps                        # Rust
godoc / pkg.go.dev                         # Go (automatic)
```

Then **fail CI when public symbols lack docstrings**. That single gate does more for
reference quality than any style guide.

## Docs must be tested

Documentation is code that runs in your users' terminals. Broken examples destroy
trust faster than missing examples.

```bash
pytest --doctest-modules            # Python doctests
cargo test --doc                    # Rust doc tests
mdbook test                         # mdBook code blocks
npx markdown-link-check docs/**/*.md   # dead links
lychee --no-progress .               # faster link checker, handles anchors
```

For untestable-by-default markdown, extract code fences in CI and execute them against
a fresh install. If a snippet cannot be run automatically, mark it `text` rather than
a language, so nobody thinks it was verified.

## Versioning

Once users are on more than one major version, docs must be versioned — a v3 doc page
answering a v2 user's search is an active harm.

- **Version at major releases only.** Per-patch versions produce dozens of dead trees.
- **Keep the current version at the canonical URL**; archive old ones under `/v2/`.
- **Banner every archived page**: "You are viewing docs for v2. [Latest is v4.]"
- **Set `rel=canonical`** to the current version so search engines stop surfacing the
  old page above the new one. This is the single most common docs-SEO failure.
- **Delete docs for unsupported versions** rather than leaving them unmarked.

## Migration guides

For every breaking change, a migration guide. This is the difference between users
upgrading and users staying on an old version forever (and then filing bugs about it).

Structure that works:

1. **Why** the change happened — one paragraph, no apologies needed
2. **What breaks** — an exhaustive list, most-common first
3. **Before/after code** for each break
4. **Automated path** — a codemod, `sed` line, or `--fix` flag where possible
5. **Escape hatch** — how to stay on the old behavior, and until when

Ship the guide *with* the release, not after. See `release-engineering`.

## Writing rules that survive translation

- **Second person, imperative.** "Run `x`", not "the user should run `x`."
- **Present tense.** "Returns a Promise", not "will return".
- **One idea per paragraph.** Three sentences maximum.
- **Front-load the answer.** Do not build to a conclusion; state it and then explain.
- **Concrete over abstract.** "10,000 rows" not "large datasets".
- **No `simply`, `just`, `obviously`, `easily`.** When a reader is stuck, these words
  tell them the problem is their intelligence.
- **Define jargon on first use**, or link it. Your users are not all native speakers.
- **Every code block is copy-pasteable** and names its language for highlighting.
- **Alt text on every image.** It is accessibility and it is SEO.

## Anti-patterns

- **Docs in the wiki.** Not versioned, not reviewed, not in the PR diff, ungrepable.
  Move to `docs/` in-repo.
- **A "Getting Started" that is actually reference.**
- **Reference written by hand.**
- **Examples that don't run.**
- **No search.** Past ~20 pages, search *is* the navigation.
- **Docs that require the site to build to be read.** Keep source markdown readable
  on GitHub; avoid generator-specific syntax in every paragraph.
- **A docs rewrite instead of a docs restructure.** Re-sorting existing pages into
  Diátaxis quadrants usually recovers 80% of the value for 20% of the work.