The gap between the tutorial and the docs

You finish the getting-started guide. It was fine — a bit slow, nothing surprising. Now you have a real thing to build, so you open the documentation, and within a minute you are reading a page that describes a configuration option in exact detail while explaining nothing about when you would ever want it.

So you go back and look for an intermediate tutorial. There isn’t one. There are nine more getting-started guides, a conference talk, and a Stack Overflow answer from 2019 that is almost your problem.

This gap is not bad luck and it is not specific to whatever you happen to be learning. It is structural, it is present in almost every technology, and it exists for a reason worth understanding — mostly because knowing the reason tells you where the missing material actually lives.

Four kinds of document, and only two get written

The most useful model here comes from a documentation framework called Diátaxis, which observes that technical writing serves four separate purposes that people constantly try to serve with one document:

• Tutorials — learning-oriented. Take a beginner through a guaranteed success. Optimised for finishing.
• How-to guides — task-oriented. Achieve a specific goal. Assume competence.
• Reference — information-oriented. Describe the machinery accurately and completely. Assume you know what you are looking for.
• Explanation — understanding-oriented. Why is it built like this? What was the alternative? What model should be in your head?

Look at what you actually hit. The getting-started guide is a tutorial. The page that ambushed you is reference. The gap you fell into is explanation, and explanation is the quadrant that routinely does not exist.

Why explanation is the one that goes unwritten

Follow the incentives and it is completely predictable.

Reference gets written because it is the part maintainers need themselves, it can be generated from the code, and its absence produces constant, specific, loud complaints. Tutorials get written because adoption depends on them — somebody’s job depends on time-to-first-success, and it is measurable.

Explanation has neither property. Existing users don’t request it: they already have the model, absorbed over two years of use, and cannot easily see that they have it. New users don’t request it either, because you cannot ask for a mental model you don’t have — you experience its absence as being personally confused, not as a document being missing. So the demand never arrives in a legible form.

And it is the most expensive quadrant to write. Reference can be mechanical. Explanation requires deciding what the reader probably believes and where that belief is wrong, which is a much harder authoring problem than describing what a flag does.

Search makes it worse

Even where explanation exists, search tends to route around it.

You arrive at documentation through a query about a specific symptom, which lands you on the reference page for the specific thing — the deepest, most context-dependent page in the set, delivered with none of the context. Reference is written to be read by someone who already has the model. It is not written to be landed on.

Then, because it is dense and precise and full of terms you half-recognise, it reads as advanced. It isn’t. It is just not teaching material, and it was never pretending to be.

Where the middle is actually hiding

The explanation quadrant usually does exist. It is just never in the docs:

• Design documents and architecture decision records. Often in the repo. The best explanation of why a system works the way it does is nearly always the document arguing for it before it existed, when the alternatives were still live.
• The maintainers’ conference talks. A talk is explanation-shaped by force — nobody can read out a reference page for thirty minutes. This is the single most underrated resource in software and it is almost all free.
• Issue threads on the decision, not the bug. Search the tracker for the argument, not the error.
• The changelog at a major version. “Why we changed this” is explanation written under pressure to justify itself.
• The book. For any technology more than about five years old, someone wrote the 300-page book, and the reason it is 300 pages is that it contains the quadrant the docs don’t.

That list is genuinely useful and I would use it. But notice how much work it is: you are assembling, by hand, from five sources, the thing that should have been one document — and you are doing it now, while blocked, which is the worst possible time to be doing research.

The real reason it was never written once

Here is the thing that makes the middle structurally different from the other three quadrants.

Reference is the same for everybody, because it describes the software. A tutorial can be the same for everybody, by assuming nothing — an assumption that is wrong for most readers but never harmfully so.

Explanation cannot do either. It is the quadrant that corrects your existing mental model, and what you already believe is different for every reader. Explaining Kubernetes to someone who has run production systems on VMs means dismantling specific assumptions about hosts and lifetimes. Explaining it to someone whose only deployment experience is a platform-as-a-service means building a model from nothing. There is no single document that does both. Try to write one and you get something that bores half its readers and loses the other half, usually on the same page.

Which is why the gap between the tutorial and the docs has stayed open for as long as there has been documentation. It is not a gap anyone forgot to fill. It is a gap that could not be filled by writing one more thing.