Nobody reads the doc

I understand there is something ironic about writing an article on documentation, even more so one that seems so aware that nobody reads documentation.

But despite being told repeatedly that documentation is a doomed endeavour, it is still everywhere. Why do we keep at it? What's the point of writing in the sand?

Don't write documentation as a prerequisite

Let's be honest here: nobody reads the doc before using a product. In the design system world, if your documentation is the only way to know which components are available, you've built something unwieldy. Designers should be able to use their software's library panels to find and understand components. Engineers should simply follow the naming conventions found in the mock-ups and easily find the equivalents in their codebases.

The ability of any product to be used without reading the instructions is a victory. Adding a layer of mandatory friction (and reading is friction for most) makes no sense.

And yet documentation is still a worthwhile investment. Using a product is not the same as using it at its full potential, using it safely, or using it in a way that will stand the test of time. This is true for your fancy coffee machine, your complicated hardware tools, and...your design system.

Write documentation for what can't be built-in

Consumers should be fine without reading the doc in many cases: the system is obvious enough that no lengthy onboarding is required to operate it. But there are things components alone can't communicate. Some guidelines can be enforced by design or code, while others are only ever going to exist as text. Your content rules (tone of voice, character length expectations, style guide etc.), your behavioural rules, your composition rules etc...

That is the value of your documentation. It's never going to be about "what's available", it's about "what we agreed were the terms and conditions".

If your consumers skip this because they feel they don't need it, your documentation is not the problem. The problem is that you have a differing idea of what your design system is: for you it's a system indeed, with its rules and conditions. For them it's a UI kit. You're playing the long game, they're building for short term. Working on this alignment will have a lot more value than working on documentation.

Documentation as an arbiter

Documentation might not be read but it is still somehow granted respect.

The people who don't read the docs still know very well that it exists, and why. Let's go back to the fancy coffee machine. If you've been using it for months without ever reading the instructions and it suddenly breaks and flashes a strange icon at you, who is at fault? Only those instructions will tell you. Maybe you've been abusing it all along and it's finally payback time. Maybe not, but without understanding the machine's laws, you can't be sure. And you have no coffee.

Design system documentation is much the same. When something goes wrong, or when someone points out a design issue, the documentation acts as the arbiter that will settle the argument. The fact that the argument would not have happened in the first place if people had read the doc is somewhat irrelevant: nobody reads it. What is relevant is that there is a source of truth, and that the parties involved know how to fix their design or coffee machine.

And to be fair to them, the larger the documentation is, the less likely it is to be read. Have you read the entire legal framework of your country? If you aren't a lawyer, it's quite unlikely (and if you are, what are you doing here?). You are still expected to follow those laws, and when something unlawful happens, the system points at them to qualify "how wrong". Design system documentation is just that. Something your policing workflows point to when things are wrong.

Context

This wouldn't be a 2026 article without the AI angle.

Your doc is AI fodder. Your consumers don't read it, sure, but their agents consume it. And since they're most likely doing everything through that filter, your most ravenous reader and your most abiding (well...) helper are that very intermediary.

So yes, you are writing your docs for a primary reader likely of the non-human kind. One which will make mistakes, and which will discard your documentation as soon as it's too large for its context or doesn't fit its current strategy. So not so different from your human consumers, but one worth considering nonetheless.

This consideration takes two forms. First, how you write needs to work for an AI reader: clear, concise, and structured for easy parsing. That's useful because your human readers likely scan documentation in the same way. Built-in links to other relevant pages, clear headings, and a logical flow help both your human and AI readers navigate the content effectively.

Second, you need to ensure your documentation lives on a platform your company's AI set-up can access. If it lives somewhere agents can't reach, you miss the chance for it to be truly useful. Your consumers delegate more and more of the "how-to" knowledge to their agents; excluding design system documentation from that introduces friction you won't be able to sustain.

Write the doc that nobody reads

Keep up the documentation work, there's really no other option. But prioritise:

• Write the doc that doesn't already live elsewhere: not in code, not in your design files.
• Write the doc that helps settle debates, and bet on them happening because the doc has not been read.
• Write the doc that helps AI help people. Which also means you've got to consider your documentation source well: make sure agents can get to it.

And if you're one of the documentation writers looking at your product shipping with inconsistencies, tired of seeing choices made that (knowingly) contradict agreed-upon guidelines, know this: it's not about the documentation then. It never was. You can't write a rulebook for people who are not interested in following it. It will only happen once your system is granted authority, and the organisational support to exercise it.

Until then, prioritise. Build the authority that will lend your documentation the usefulness it deserves, even if it still remains unread.