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.