Great reading
Everyone should have a sense of documentation, for what is more important than knowing what we think, we want etc and to explain it in a way others will get it?
This connects to the usefulness of making a manual of me like this one I made manual-of-alex.html - easy to do it with AI but you can also do it on their site or manually. I’d recommend starting with a pen and paper.
Practical application:
Based on this, here is what a typical README should include:
Introduction, why the user should care, which pain points are addressed by this project.
Sections with links to them.
Tutorial, an introduction to how this works in practice, made to be repeatable and strong.
How-to, once the user is familiar with how this works, they will have questions for certain use cases. Specific naming.
Reference, the facts about this and how it works. Same structure as the codebase. Informative. Probably not in the readme.
Then finally discussions which is where you say how this should be used? give context, how it stands with other things.
Avoid putting stuff where it doesn’t belong. Explanations in the middle of doing or the opposite. These quadrants need to be split.
This is the skill generated from this.
# Documentation: the four-quadrant system
Based on the Divio documentation system (Daniele Procida, https://docs.divio.com/documentation-system/).
There is no single thing called "documentation". There are four kinds, and they
serve different readers with different needs. Each needs its own document.
## The two axes
| | Study (learning) | Work (doing) |
| --------------- | ------------------------ | --------------------------- |
| **Practical** | Tutorial | How-to guide |
| **Theoretical** | Explanation | Reference |
## The cardinal rule
**Never mix quadrants inside one document.** Almost every documentation failure
is a quadrant violation:
- explanation smuggled into a tutorial ("before we continue, note that Django's
ORM uses the active-record pattern...") — the beginner stalls
- how-to steps buried in reference — the fact becomes unfindable
- reference tables inside a tutorial — the learner loses the thread
- a tutorial that stops to offer three alternative approaches — the learner now
has to make a decision they lack the knowledge to make
When a section starts serving a second quadrant, cut it out and link to it.
---
## 1. Tutorial — learning-oriented
**Analogy:** teaching a child to cook. The dish barely matters; the confidence
and the craft knowledge do.
**Purpose:** take a beginner by the hand through a series of steps to complete a
meaningful project, so they finish knowing they *can*.
MUST:
- work reliably, every time, on every supported system — a broken tutorial
destroys trust faster than no tutorial
- produce a visible, comprehensible result at every step
- build progressively: simplest concrete action first
- take full responsibility for the journey; the author decides what is learned
- keep explanation to the bare minimum needed to proceed
MUST NOT:
- ask the learner to appreciate an abstraction before they have met the concrete
- include extended discussion (important — just not here)
- mention alternatives, options, or "you could also..."
- show advanced technique or best practice
**Test:** a motivated beginner following it word for word ends with a working
thing and no unresolved confusion.
---
## 2. How-to guide — goal-oriented
**Analogy:** a recipe. Assumes you can already cook.
**Purpose:** answer a specific question that only a user with some competence can
even pose. "How do I ...?"
MUST:
- be titled `How to <do the thing>` — "How to create a web form", never a noun
phrase like "Class-based views"
- give steps in a working sequence
- stay practical: **usability beats completeness**
- allow flexibility so the reader can adapt it to their near-miss situation
- link out for concepts rather than explaining them inline
MUST NOT:
- teach the basics the reader already has
- explain concepts or theorize
- chase cast-iron repeatability the way a tutorial must (it may start
mid-process, and assume a reasonable starting state)
- include background that does not serve the goal
**Test:** the title matches a sentence a real user would type into search.
---
## 3. Reference — information-oriented
**Analogy:** an encyclopedia entry on ginger. Facts about provenance, behaviour,
and properties. It does not teach you to cook with it.
**Purpose:** describe the machinery accurately, so a working user can look up a
fact and get back to work.
MUST:
- **mirror the structure of the codebase**, so the reader can navigate code and
docs in parallel — this also exposes what is missing or stale
- be austere and consistent in structure, tone, and format across every entry
- state constraints, gotchas, and interactions
- describe classes, functions, parameters, return values, errors, config keys
- include the minimum usage needed to operate the thing (how to instantiate,
how to invoke)
- stay accurate and current; wrong reference is worse than absent reference
MUST NOT:
- explain concepts
- teach how to accomplish a task
- contain opinion, speculation, or discussion
**Test:** every public surface appears, in the same shape, with no argument.
Generate it from source where possible — hand-maintained reference rots.
---
## 4. Explanation — understanding-oriented
**Analogy:** a book on food and cooking in the context of history, science, and
technology. It analyses; it considers multiple perspectives.
**Purpose:** illuminate the topic. Read at leisure, away from the keyboard.
Broadens the reader's understanding of *why*.
MUST:
- give context and background
- state design decisions and the reasons behind them
- cover technical and historical constraints ("we did it this way because in
2019 the upstream API had no batch endpoint")
- weigh alternatives that were considered and rejected, and the trade-offs
- admit opinion, and attribute it
MUST NOT:
- instruct on performing a task
- act as reference material
- duplicate what the other three quadrants already do
**Scope:** unlike the other three, its boundaries are arbitrary — a topic is
whatever you judge a reasonable area to cover at once.
**Test:** it answers "why is it like this?" for someone who already knows how to
use it.
---
## Where each quadrant lives in a repo
| Quadrant | Home |
| ------------ | ----------------------------------------------------------- |
| Introduction | `README.md` — what this is, why the reader should care, which pain it removes, then links to the four sections. Keep it a doorway, not a manual. |
| Tutorial | `docs/tutorials/` — usually just one, "getting started" |
| How-to | `docs/how-to/<how-to-x>.md` — grows over time, one per real question |
| Reference | `docs/reference/` mirroring source layout, or generated from docstrings/types |
| Explanation | `docs/explanation/`, architecture decision records (`docs/adr/`), `WHY.md` |
Extras that carry real weight:
- **`WHY.md`** (batman's ritual) is pure explanation quadrant: why this project
should exist at all. Write it before the code, not after.
- **ADRs** are explanation, one decision per file, dated, including the rejected
options. An ADR is the cheapest possible defence against re-litigating a
settled decision six months later.
- **Code comments explain WHY, not WHAT.** The what is in the code; if the code
is unclear, fix the code. The why cannot be recovered from the source — a
comment naming the constraint, the bug it works around, or the reason the
obvious approach fails is the highest-value comment there is.
- **`ponytail:` comments** name a deliberate shortcut and its upgrade path.
Harvest them with `/ponytail-debt` rather than letting them rot.
## Practical rules
1. **Pick the quadrant before writing a line.** State it in the doc's frontmatter
or heading if it helps.
2. **Update reference in the same commit as the code change.** Reference that
lags the code is a liability.
3. **Do not write a tutorial for an unstable API.** It will break and burn trust.
4. **A missing how-to is a support question you will answer repeatedly.** Every
second time you explain something in chat, it becomes a how-to.
5. **Docs are shared state.** Anything learned that the repo does not record goes
into the repo — its `CLAUDE.md`, an ADR, or the relevant quadrant.