Why this session exists
You have felt it: the README that teaches when you need steps, the wiki page that lists options when you need to understand why. One framework explains all of it. Diátaxis, created by Daniele Procida (free at diataxis.fr), says users need four distinct kinds of documentation - tutorial, how-to guide, reference, explanation - and that most doc pain is one kind doing another kind's job. Pulse already has an audience statement, a plan, and a README; today we find the gap the framework exposes.
docs/how-to-diagnose-low-day.md, written for the on-call engineer your audience statement promised to serve back in Session 1.
The map 8 min live
Two questions generate the whole framework. Is the user doing something practical (action) or acquiring theory (cognition)? And are they at study, building skill (acquisition), or at work, applying it (application)? Two axes, four quadrants, four kinds of docs. Each quadrant answers a different question a user actually asks.
LiveTwo axes, four quadrants3 min▶
Each kind of documentation answers one canonical user question, and refuses the other three:
- Tutorial - "Can you teach me to...?" A lesson. The user is at study, doing practical work, and the teacher is responsible for their success: visible results at every step, one safe path, no alternatives, minimal explanation, absolute reliability.
- How-to guide - "How do I...?" Directions for a goal. The user is at work, already competent, and needs steps that adapt to their real, messy situation.
- Reference - "What is...?" Description. Dry, list-like, consulted while working. It mirrors the structure of the product itself, like a map mirrors territory.
- Explanation - "Why...?" Discussion. Read away from the keyboard, when the user steps back to understand context, design decisions, and trade-offs.
LiveTutorial vs how-to: the most-conflated pair3 min▶
Both are practical and step-shaped, which is why merging them is the single most common mistake in software docs. But they serve opposite situations:
| Tutorial | How-to guide | |
|---|---|---|
| User is | at study, building skill | at work, mid-task |
| Setting | contrived and safe, chosen by you | their real, messy environment |
| Path | one fixed linear path, no alternatives | branches for real-world variation |
| Responsibility | the teacher owns the learner's success | the user owns the outcome |
| Analogy | a cooking lesson with an instructor | a recipe in your own kitchen |
The tell: a "tutorial" that opens with "depending on your setup, you may want to..." is a how-to guide in costume. A "how-to" that pauses to explain what a virtual environment is has a tutorial trapped inside it.
The getting-started page that served no one. A data platform's "Getting started" mixed a toy walkthrough with production deployment options. Newcomers hit the branching options and froze; experienced engineers waded through the toy example to find the one flag they needed. Split into a tutorial (fixed sample data, guaranteed outcome) and a deployment how-to, both audiences got faster - the content barely changed, only its sorting did.
Self-studyReference vs explanation: the litmus test2 min read▶
The cognition side has its own commonly-fused pair. The litmus test is when the reader has it open:
- Reference is consulted WHILE working. It is austere on purpose: tables, parameter lists, one true format. It states facts and cites nothing but the product. Its structure should mirror the product's structure, so the user can navigate the doc by navigating their mental model of the code.
- Explanation is read when stepping back. It is discursive and wide-angle: why the design is this way, what the alternatives were, how this connects to that. It is the one quadrant where opinion and perspective are welcome.
If a "reference" page starts arguing for a design decision, cut the argument and move it to an explanation page. If an "architecture overview" keeps getting opened mid-incident for one config value, that value belongs in reference. Session 6 builds both kinds for Pulse.
The compass and the workflow 7 min live
The map tells you what the four kinds are. The compass tells you where you are standing right now, with a real messy page in front of you. And the workflow rule tells you what to do about it - which is emphatically NOT what most teams do first.
LiveThe compass on messy real pages3 min▶
Real pages rarely arrive pre-labeled. The compass is the two questions from the map, applied to whatever is in front of you: action or cognition? then acquisition or application? Ask them about each chunk of a page, not the page as a whole.
Worked example: "Is our wiki page on the alert system a how-to or a reference?" Run the compass section by section and the honest answer is: it's three docs fused. The threshold table (cognition + application) is reference. The what-to-do-when-it-fires steps (action + application) are a how-to. The paragraph on why we alert on volume instead of latency (cognition + acquisition) is explanation. The page isn't bad because the facts are wrong; it's bad because three different readers each have to wade through the other two readers' content.
LiveThe iteration rule: never restructure top-down3 min▶
The classic failure mode after learning Diátaxis: declare a grand migration, create four empty sections labeled Tutorials, How-to, Reference, Explanation, and start shoveling the old wiki into them. The diataxis.fr site itself is blunt about this: don't do that, it's horrible. You burn weeks, the empty skeleton demoralizes everyone, and the fused pages stay fused - just in new folders.
The prescribed workflow is deliberately small:
- Pick any small piece of the existing docs. Literally any page, wherever you happen to be.
- Assess it with the compass. What is it trying to be? What is it fused with? What single thing would most improve it?
- Make ONE improvement and publish it. Move the reference table out. Sharpen one title. Delete one digression.
- Repeat. Structure emerges from many small correct moves, the way a city street grid emerges, not the way a planned monument does.
The mindset shift underneath: documentation is never "finished", and under this workflow it is always complete - every published state is a valid, shippable state. There is no half-migrated limbo.
Self-studyComplex hierarchies: audience first, then the four needs2 min read▶
Big products break the naive four-folder layout: a platform serving analysts, engineers, and admins can't share one tutorial section. The guidance for scale:
- Segment by user type or context FIRST, then apply the four needs within each segment. "Analyst docs" gets its own tutorial, how-tos, reference; so does "operator docs". The audience statement from Session 1 is exactly this segmentation, already written.
- Cap contents lists at roughly seven items. Past that, readers stop scanning and start searching, which means your structure has stopped helping. Split or regroup.
- Make landing pages readable overviews, not bare link farms. A good landing page tells the reader which segment they are and which need they have, in prose, before showing them the list.
Compass-audit the Pulse doc set ★ 6 min · everyone follows
Pulse now has four prose artifacts: docs/AUDIENCE.md, docs/PLAN.md, docs/notes-rewrite.md, and the README from Session 4. Run the compass over each and find what the set is missing.
Compass the README: the quickstart with expected outputs is action + application (how-to), the config table is cognition + application (reference). Verdict: a fusion - and that's fine. A README is a front door, not a quadrant; its job is to route readers, and short embedded slices of two quadrants is exactly what a front door does.
Compass notes-rewrite.md from Session 2: it mostly says why things are the way they are. Cognition + acquisition: explanation-ish. Park it; Session 6 gives it a real home.
Now check the map against docs/AUDIENCE.md. The secondary audience is the on-call engineer at 2am whose job is to diagnose a LOW alert day. Action + application. That is a how-to guide - and no such doc exists. The gap found itself.
Write the how-to: diagnose a LOW day ★ 10 min · build your own
Time to fill the gap. A how-to guide is recipe-shaped: a precisely-named goal, prerequisites, numbered actionable steps, zero teaching, zero digression. Where the reader might need background, we link to reference instead of explaining inline.
Create docs/how-to-diagnose-low-day.md. Note the title names the exact task in the user's own words - a how-to's title is its search result.
Copy the guide below. Read it as the 2am engineer: every step is an action with a decision at the end, and nothing explains how the pipeline works.
Check it against the how-to rules: prerequisites stated, steps adapt to the real world (the branches live inside steps 2-4), no teaching, ends when the goal is reached.
Quadrant-sort your own team wiki ★ 6 min · build your own
The compass only becomes yours when you run it on pages you actually own. This exercise takes five pages and produces a number you can report: how many of your docs are fused.
Pick five pages from your team's wiki or docs folder - the five most-visited if you know them, otherwise the five you touched most recently.
Compass each one section by section: action or cognition, study or work. Give each page a verdict: one clean quadrant, or fused (name the quadrants inside it).
Count the fused ones. Three or more out of five is typical, so don't be discouraged - be specific. For ONE fused page, name the single improvement you'd publish this week, per the iteration rule.
Do not create four empty folders. Not even a little bit.
The one-page-a-week migration. A five-person data team scored 9 of their 12 wiki pages as fused, then fixed exactly one page per week: usually by moving a reference table out of a how-to. After a quarter, without ever announcing a restructure, their docs had quietly become navigable - and the habit survived because no single week's work exceeded an hour.
Try it yourself - this week ◐ 30-45 min total
- Finish
docs/how-to-diagnose-low-day.mdin your Pulse copy if you didn't complete it live, and walk it once against a real run'sdaily_metrics.csv. - Complete the Demo 3 quadrant-sort on five real pages, and publish ONE small improvement to one fused page. One. Publish it.
- Run the Part 1 ★ Try it now compass drill until the two questions feel automatic - the goal is naming a quadrant in under ten seconds.
- Read the Self-study cards: the reference vs explanation litmus test, and complex hierarchies. Both come due in Session 6 when we build Pulse's reference docs.
- Optional depth: the theory pages at diataxis.fr (foundations, the map, quality) explain WHY the two axes carve documentation at its joints - a satisfying read once you've used the compass in anger.
Official sources covered
This session teaches the working content of these diataxis.fr pages. What stays with the original: the full theory essays and Procida's worked prose examples, which reward a direct read.
Three questions before you go 🎯 ◐ 90 seconds
1 · An engineer mid-incident needs the exact meaning of the alert column in daily_metrics.csv. Which doc serves them?
Compass it: they need to KNOW something (cognition), and they are at WORK (application). That quadrant is reference. The other two would make a 2am incident longer.
2 · What actually separates a tutorial from a how-to guide?
The difference is the user's situation, not length or skill flattery: contrived-safe vs real-world, single path vs branching, teacher-responsible vs user-responsible. It's the most-conflated pair for a reason.
3 · Your team just learned Diátaxis and wants to fix the wiki. What does the framework say to do first?
The top-down empty-skeleton restructure is the failure mode the site warns against by name. Structure emerges from small published improvements; docs are always complete, never finished.