Every design system has documentation.
Not every design system has documentation that gets used. These are different things, and the gap between them is where most adoption problems quietly live.
The documentation was thorough. Comprehensive. Well-structured. It had a table of contents, a search bar, and a changelog that was updated religiously for four months before the person who maintained it changed teams.
We built ours on Zeroheights. Every component documented. Every variant annotated. Every usage guideline written. The kind of documentation you are proud to show in a presentation.
What practitioners wanted was the code block. The snippet they could copy, paste into the codebase, and move on. The faster they could find it, the better. Everything else — the rationale, the guidelines, the decision history — was in the way.
That was not a Zeroheights problem. It was not a documentation quality problem. It was a documentation purpose problem.
The Documentation Trap
Most design system documentation is written for the team that built the system, not the team that needs to use it.
It is organized around the system's architecture. Component by component, property by property, variant by variant. This structure makes perfect sense to someone who understands how the system was built. It makes no sense to a front-end engineer trying to implement a specific UI pattern under deadline pressure.
The engineer doesn't need to know everything about the Button component. They need to know how to implement a loading state on a Button in a form submission flow. Those are different questions. Most documentation answers the first one and ignores the second.
The documentation was organized around the system. The user was organized around a problem. They were never going to meet in the middle.
The Four Types of Documentation Practitioners Actually Need
Dan Saks, a technical writer at Divio, identified four types of documentation. Design system teams rarely produce all four. Most produce one and call it complete.
Type 1 — Tutorials
Learning-oriented. Gets a new practitioner from zero to their first successful implementation. Step by step. Assumes nothing. Celebrates completion.
Most DS teams skip this entirely. The assumption is that practitioners will figure it out. Some do. Most spend forty minutes in the wrong section of the docs before opening a Slack channel and asking a human.
Type 2 — How-To Guides
Task-oriented. Answers a specific question a practitioner already has. "How do I implement a disabled state on this input?" "How do I handle a loading state in this button?" "How do I extend this component without breaking the token architecture?"
This is the documentation practitioners reach for at 3pm on a Wednesday. It is also the documentation most teams never write because it requires knowing which questions practitioners are actually asking.
Your Slack channel is a backlog of undocumented how-to guides. Every question asked in Slack that doesn't have a documentation link in the answer is a documentation gap.
I have worked in organizations where the documentation platform was impeccable and the adoption was not. The format that changed behavior was not a better tool. It was a chat message. Someone typing into an MS Teams channel: where is this, how do I do this, what is the right pattern here. Answered in the moment, in the channel, by whoever knew.
Not a knowledge base. Not a structured guide. A conversation. That is a terrible solution. It is also, frequently, the one that works.
Type 3 — Reference
Information-oriented. The complete technical specification. Every prop. Every variant. Every token. This is what most DS teams produce first and only.
Reference documentation is essential. It is also the last thing a practitioner reads. They come to reference docs after they already understand the system. Before that point, reference docs are a wall of information they don't yet have the context to navigate.
Type 4 — Explanation
Understanding-oriented. Answers the question "why." Why was this component built this way? Why does this token exist? Why does the system make this trade-off?
Explanation documentation builds practitioners who can make good decisions without asking for help. It is the highest-leverage documentation type and the one most DS teams never write because it requires articulating decisions that were made intuitively and never written down.
How to Audit What You Actually Have
Take your current documentation and sort every page into one of four columns: Tutorial, How-To, Reference, Explanation.
Most DS teams will find 80% of their documentation in the Reference column. Some will find Tutorial content. Very few will find any How-To or Explanation content.
Then look at your Slack channel. Find the ten most frequently asked questions in the last three months. Those questions are your How-To backlog. Every one of them is a document that needs to be written.
The Quick Win: Write One How-To Guide This Week
Find the most frequently asked question in your DS Slack channel in the last month. Write a how-to guide that answers it. Not a reference page. A task-oriented guide that starts with the question as the title and ends with a working implementation.
Post the link in Slack the next time someone asks the same question. Measure how many times that link gets shared in the following month.
"If the same question keeps getting asked in Slack, that question is not answered in your documentation. It is a symptom of a documentation gap wearing the costume of a helpful community."
The Argument
Documentation is not a deliverable. It is a service. And a service that doesn't solve the problem the user actually has is just a well-organized reason to ask for help from a human instead.
Disagree loudly. Inspire boldly.
And remind me — falsely if needed — that somewhere a design system how-to guide answered a question before it got asked in Slack.
What is the most frequently asked question in your DS Slack channel that doesn't have a documentation link in the answer? 🤔
