Documentation is a product and you should staff it like one

Ask any engineering team whether documentation matters and they will say yes. Ask who owns it and you will get a pause.

That pause is the entire problem.

the four kinds, and why mixing them fails#

The taxonomy that fixed documentation for me — and it is not mine, it is the Diátaxis framework — is that there are four distinct kinds and they have incompatible goals.

Tutorials teach a beginner by having them do something that works. The goal is a successful experience, not completeness. A tutorial that mentions every option has failed. It should be prescriptive, opinionated, and it should work exactly as written, every time.

How-to guides help someone accomplish a specific task they already understand. "How to configure TLS." Goal-oriented, assumes competence, skips explanation.

Reference describes the machinery precisely and completely. Every parameter, every return value, every error. Boring by design. Generated where possible.

Explanation provides understanding. Why is it designed this way? What are the trade-offs? What is the mental model? This is the kind that is almost always missing and the kind that most reduces support burden.

Most documentation fails because it tries to be all four at once. A tutorial that stops to explain architecture loses the beginner. A reference page with a narrative is hard to scan. Separate them, label them, and each one gets better.

what "staff it like a product" means#

One named owner. Not "the team." A person whose review includes it.

A budget in the sprint. Documentation work sized and scheduled alongside features, not appended to the end of a ticket where it gets cut.

Metrics. Support tickets that a doc would have prevented. Search queries with no results. Time-to-first-successful-request for a new user. Page-level feedback. Every one of these is measurable and almost nobody measures them.

A definition of done that includes it. A feature is not shipped until it is documented. This is either enforced or it is a slogan; there is no middle.

the practices that actually move the needle#

Docs live with the code. Same repository, same pull request, same review. Documentation in a separate wiki drifts within one quarter, guaranteed, without exception.

Test the examples. Every code sample in your docs should be extracted and run in CI. Broken examples are worse than no examples — they destroy trust in the whole document, and every set of docs has them, because they were correct when written.

Write the failure cases. The single highest-value section in any documentation is "common errors and what they mean." This is what Stack Overflow existed to provide and it is the thing your docs almost certainly lack.

Go read your support queue. Every recurring question is a documentation gap with a measured frequency attached.

Date and version everything. "This page describes v4.2, last updated 2026-01-15." Undated documentation is untrustworthy documentation, because the reader cannot tell whether it is current.

Make the first example work. The single most common documentation failure: the quickstart does not run. Someone changed a default, renamed a parameter, required a new config field. Test the quickstart in CI, on a clean environment, on every release.

the argument that gets budget#

Documentation is deflection. Every question answered by a doc is a question not asked of an engineer.

Count your support load. Estimate the fraction that is documentation-shaped — "how do I," "what does this error mean," "does it support." In most organizations it is more than half.

Now price that in engineer-hours. That is your documentation ROI, and it is usually large enough to fund a technical writer, which is the actual right answer and which almost nobody does.

the new reason it matters#

Your documentation is now also a model's training data and a model's retrieval corpus.

When a developer asks an assistant about your library, the answer is synthesized from your docs. If your docs are wrong, incomplete, or ambiguous, the assistant confidently produces wrong code, and the user blames your library.

You have less control over how your project is explained than you did three years ago, and the only lever you have is the quality of the source material.

That is a strange new incentive and it is the strongest argument for good documentation that has ever existed.