docs-architecture

name

docs-architecture

description

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".

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.

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:

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.

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.