progressive-docs

Progressive docs

Goal: replace the "monolithic README anti-pattern" with a small tree of focused docs that readers discover in increments. Each doc has one job. The top-level entry point is short and links out.

Workflow

Three phases. Don't skip phase 1 — it's how we avoid generating speculative docs.

Phase 1 — Audit

1. Read the project shape, not just the docs. Look at manifest files (pyproject.toml, package.json, Cargo.toml...), entry points, public surface (CLI commands, exported APIs, HTTP routes), and config files (.env.example, etc.). Skim representative source files. The point is to know what should be documented before checking what is.
2. Identify audiences. Who actually reads docs for this project?
   • End-user: installs and uses it (CLI tools, libraries, services)
   • Contributor: changes the code (anyone who'd touch the repo)
   • Operator: runs it in production (services, scheduled jobs, anything with runtime config) Most projects have 1–2. A research script may have zero true end-users — don't invent audiences.
3. List existing docs. README*, docs/, CONTRIBUTING.md, ARCHITECTURE.md, CHANGELOG.md, inline docstrings — everything.
4. Diff expected vs. existing. Use references/audit-heuristics.md to know what's expected for the project shape.
5. Present a gap report and stop. Don't write files yet. The user picks what to fill.

Phase 2 — Plan

The user picks which gaps to fill. If they said "do everything," confirm scope first ("I'll write 6 files: index, getting-started, architecture, configuration, how-to-add-a-tool, contributing — sound right?") before generating. The point is to avoid dumping 20 files unannounced.

Phase 3 — Remediate

Write the chosen docs. See Output structure and Writing principles below.

Diátaxis at a glance

Every doc is one of these — pick one and stick to it:

Type	Reader's job	Voice	Examples
Tutorial	"I'm new — teach me by doing"	Lesson, hand-holding	"Build your first plugin in 10 min"
How-to	"I have a specific problem — solve it"	Recipe, terse	"Add a new tool", "Deploy to staging"
Reference	"Look up an exact fact"	Dry, exhaustive	All env vars, all CLI flags
Explanation	"Understand why"	Discussion	"Why we use LangGraph instead of plain ReAct"

If a doc starts mixing two of these, split it — the mix is the bug. For deeper guidance and how to handle borderline cases, read references/diataxis.md.

Output structure

Default — Diátaxis tree:

docs/
├── README.md           # 1-screen index pointing out
├── tutorials/          # ordered learning path
├── how-to/             # task-oriented recipes
├── reference/          # exhaustive lookup
└── explanation/        # background, decisions

Flat fallback for tiny projects (<5 useful docs):

docs/
├── README.md
├── getting-started.md
├── architecture.md
└── ...

Pick the flat shape when the full Diátaxis tree would have empty quadrants. A solo-author script with three users and no API surface doesn't need four directories.

Writing principles

1. Read before writing. Open the actual code, manifests, configs. Cite real symbols, real flags, real env vars. Speculation is the failure mode here — if you can't tell from the code, say so or find out.
2. One job per file. A how-to that drifts into "and here's why we made this choice" should split — move the why into an explanation doc and link.
3. Short entry, long leaves. docs/README.md is roughly one screen and almost entirely links. Each leaf doc fits under ~150 lines; if a topic is bigger, split it again. Smaller files are more discoverable, more skimmable, and easier to keep accurate.
4. Cross-link generously. Each doc names what came before, what comes next, what's related. Progressive disclosure depends on these breadcrumbs.
5. Skip what well-named code already says. "The read_file tool reads a file" is filler. Document what the reader can't infer: invariants, tradeoffs, surprising behavior, the shape of the whole.
6. Match the project's voice. Use the terminology already used in the code and any CLAUDE.md. Don't import jargon that isn't there.
7. Mark known unknowns. If you can't tell whether something works on Windows, write "Tested on macOS/Linux; Windows untested" — better than silently generalizing.

When NOT to write a doc

• The information is already obvious from the code (e.g., a 20-line utility script with clear function names).
• It would just restate the README in another file with rearranged words.
• Nothing in the codebase actually does what you'd be documenting (don't speculate about future features).
• The project genuinely doesn't have that audience (don't write a contribution guide for a solo notebook).

A skipped doc is a feature. Documentation theater — files that exist to look thorough but say nothing — is a regression, not a contribution.

Templates

Starter skeletons for each Diátaxis quadrant live in references/templates.md. Adapt them; don't paste verbatim. Templates exist to keep shape consistent, not to be copy-pasted as the final output.

Project-shape heuristics

Different project types have different "expected" doc sets. Quick examples:

• CLI tool with [project.scripts]: getting-started, command reference, how-to per common task.
• Library: tutorial, API reference, explanation of core abstractions.
• Web service: getting-started, configuration reference, ops/deployment, architecture.

Full table in references/audit-heuristics.md — read it during Phase 1 to know what to look for.