The Docs Framework Nobody Talked About in 2023 Is Back — Because Your Docs Have a New Reader

Something odd is happening in developer circles. A documentation framework that peaked around 2020 and quietly faded is climbing back up the aggregators. It’s called Diátaxis. But the reason people are dusting it off has almost nothing to do with writing better docs for humans. It’s about making docs legible to machines.

One caveat before we go further. I went looking for a groundswell of recent community discussion on this and mostly came up empty — a handful of threads, no viral moment. So treat this less as a report on a debate and more as a reading of where the framework sits against what’s actually changing in how software gets built.

What Diátaxis Actually Says

Diátaxis is a taxonomy assembled by Daniele Procida, who spent years working on Django’s documentation. The claim is deceptively simple: technical documentation comes in exactly four kinds, and only four.

• Tutorials — hands-on lessons for someone brand new, where the goal is learning by building
• How-to guides — task-oriented recipes for someone who already knows the tool and has a specific problem
• Reference — API listings, config keys, parameter tables. Facts, nothing else
• Explanation — the why. Design rationale, background, trade-offs

The four buckets aren’t the point. The rule is: never mix them. Drop a reference aside into the middle of a tutorial — “by the way, this flag also accepts three other values” — and the beginner loses the thread. Bury design philosophy in your reference tables and the person under deadline pressure can’t find the value they came for.

Procida frames it on two axes: practical versus theoretical, and studying versus working. Cross them and you get a quadrant, and each cell maps to one of the four document types. That’s why engineers took to it. It isn’t vague advice to “write clearly.” It’s a test you can run on the paragraph in front of you right now.

Why It’s Resurfacing Now

The framework had its moment around 2020. Django, Gatsby, and Cloudflare all restructured docs around it. Then the consensus settled into something like “great in theory, hard to sustain,” and the conversation moved on.

Coding agents changed the math. Over the course of 2025, tools like Claude Code and Cursor went from novelty to default. The heaviest reader of your library’s documentation is no longer a person. An agent takes a task, ingests the docs wholesale, extracts what looks relevant, and writes code against it.

That’s where it breaks. A human skimming a messy page does constant unconscious filtering — this block is illustrative, that one is the real API, this warning is a counterexample. Agents are worse at that filter than people assume. They lift tutorial sample code into production configs. They copy the snippet that appeared under a heading literally titled “don’t do this.” When genres are blended on a page, the reader who pays the highest price is the machine.

The “don’t mix” rule Diátaxis has been preaching since 2017 was a style recommendation for humans. For agents it’s an accuracy problem.

llms.txt and the Second Face of Documentation

The adjacent trend here is llms.txt — a file that tells language models what’s worth reading on your site and where, the way robots.txt guides crawlers. A meaningful chunk of documentation sites have started shipping one.

Try to write one and you hit a wall almost immediately. Curating that link list requires each page to answer a question about itself: is this for someone getting started, or someone looking something up? If your structure can’t answer that, your llms.txt is just a pile of URLs with no signal in it.

Which leads somewhere slightly deflating for anyone hoping to bolt on an AI layer. You don’t need a separate machine-readable format. You need the docs you already have to stop mixing genres. Practitioners who’ve done both tend to report the same thing: stripping blended content out of existing pages beats generating a new AI-specific artifact.

The Counterarguments Are Real

Not everyone buys this. The pushback comes in three flavors.

First, nobody searches by quadrant. Real users don’t think “I should check the how-to section.” They paste an error message into a search box. Split everything four ways and you can force someone to bounce across three pages to resolve one question that a single well-written page could have handled.

Second, maintenance cost. Document one feature four times and every change means four edits. Unless you’re staffed like Stripe, one or two quadrants go stale, and stale docs are worse than no docs. The tutorial that references a deprecated flag actively costs you support tickets.

Third, and more fundamentally: agents keep getting better at inferring context. Is it wise to restructure an entire documentation estate around a limitation that might be largely gone in eighteen months? Building organizational process around today’s model weaknesses has a poor track record.

All three land. But the first two are really arguments against applying Diátaxis dogmatically. Procida himself has described it as a compass, not a spec. The point was never to enforce four physical directories. It’s to make you conscious of what kind of thing you’re writing at the paragraph level.

What To Actually Do About It

You don’t need a documentation replatform. In rough order of return on effort:

Open your most-read page — usually the README. If installation steps, usage examples, an options table, and design background are all tangled together on it, that’s your first surgery. Just separating the part you follow along with from the part you look things up in changes the experience for humans and agents alike.

Next, label your code samples. One line — “minimal example, not production-ready” or “recommended production config” — meaningfully cuts down on agents copying the wrong block. Humans benefit too, which is usually the tell that a change is worth making.

Then strip the chatter out of reference. If a parameter table contains a sentence like “we thought long and hard about this design,” that sentence belongs in an explanation page.

The Part That Nags

Diátaxis is trending again not because the framework got better. It’s because the audience changed. Humans muddled through disorganized docs for thirty years. Agents don’t muddle. They produce confidently wrong code instead, and you find out in review — or in production.

Here’s what sits uneasily with me. It’s getting harder to tell whether we’re cleaning up documentation for readers or optimizing it for crawlers. Right now those two goals point in mostly the same direction, which is lucky. At some point they’ll diverge — a structure that’s ideal for retrieval but tedious for a person, or vice versa. I genuinely don’t know which one I’d pick. Which quadrant is your team’s documentation sitting in today, and do you know?