Most documentation fails before the first sentence. It fails at the decision about what the page is for.
Diátaxis — the documentation framework sitting on the Hacker News front page again — makes that decision the whole game. It says there are four distinct user needs, four corresponding forms of documentation, and that nearly every bad doc page is one of these forms doing another form’s job.
The four: tutorials, how-to guides, reference, and explanation.
The quadrant in one minute
Split documentation along two axes: does it serve study or work, and does it describe steps or knowledge.
- Tutorials are lessons. A beginner follows along and builds something small that works. The goal is the learner’s confidence, not the thing they built.
- How-to guides are recipes. A competent user has a real task — deploy the service, rotate the key — and wants the shortest correct path.
- Reference is the dictionary. Parameters, return values, options. Dry, complete, accurate. Nobody reads it for fun and it should not try to be fun.
- Explanation is the essay. Why the system is shaped this way, what the trade-offs were, what the alternatives are. Context, not instructions.
That is the whole framework. The discipline is keeping them apart.
Why mixing them kills the page
A tutorial that keeps stopping to explain theory loses the beginner, who just wants the next step to work. A how-to guide that starts with three paragraphs of background loses the engineer, who is mid-incident and needs the command. Reference full of helpful tips becomes impossible to scan. Explanation interrupted by setup steps convinces nobody.
Every engineer has read the page that does all four at once. It opens with a conceptual overview, detours into a quickstart, apologizes that some options are out of scope, and ends with an incomplete list of flags. Nobody wrote that page. It accreted. Each contributor added the kind of content they had in hand, and the page now serves no one.
Diátaxis gives you the question that prevents it: what is this page’s job? One job. If a new section answers a different need, it is a different page.
The authorship payoff
The framework’s quiet benefit is for the people writing docs, not just reading them. Cloudflare, Gatsby, and Vonage all cite it for the same reason: when the four forms are explicit, contributors know where a piece of knowledge goes. “Where should this live?” stops being a debate. A gotcha goes in the how-to. The rationale goes in the explanation. The new flag goes in reference. Done.
It also makes gaps visible. Plenty of projects discover they have reference and tutorials but zero explanation — so users can operate the tool but never learn to trust it. Others find the opposite: beautiful architecture essays, no working quickstart, and a trial-to-paid rate to match.
Docs are only half the visibility problem
The reason documentation matters at all is that knowledge lives too far from the people who need it. That distance shows up inside the team too. Why did we build it this way? What changed while I was out? The answer exists — in commit messages, PR discussions, review comments — but scattered across tools, so the team holds meetings to reconstruct it.
That is the problem Kahoona attacks from the other end: it puts live GitHub activity — commits, PRs, CI — next to the tasks it belongs to, so the “why” and “what changed” are written down once, where the work happened, instead of re-explained every Monday.
👉 See what your team is actually shipping — free to start
Where to start
You do not need a restructure to get value. Pick your five most-visited doc pages and ask the one question of each. You will find at least one tutorial that is secretly a how-to, and one reference page smuggling in a lesson. Split them. It takes an afternoon, and it is the rare docs improvement users notice the same week.
Related: The Bus Factor Is a Documentation Problem · How to Onboard a New Dev Without a Single Meeting