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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: the-open-agent
• Source: the-open-agent/oss-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.