Documentation Nobody Reads Is Not Documentation

A component with no usage guidelines gets used however the next person interprets it, which is how the same button ends up meaning three different things across a single product: primary action here, secondary action there, destructive action somewhere else entirely, each choice locally reasonable and collectively incoherent. The component itself was never the problem — it was built well, tested, documented even. What was missing was any reliable way for the person using it, in the moment they needed to decide, to know what it was actually for.

The instinct when this happens is to write more documentation, and more thoroughly. A team notices the inconsistency, gets embarrassed by it in a design review, and responds by producing a genuinely excellent usage guide: clear do's and don'ts, annotated examples, edge cases called out explicitly. It's a good document. Six months later, the same inconsistency is back, sometimes worse, and the team is confused, because by any reasonable measure the documentation problem was solved. What wasn't solved was the distance between where that guidance lives and where the decision actually gets made.

Consider a mid-sized team that builds a genuinely thorough component library guide in a wiki — Confluence, Notion, a dedicated docs site, it doesn't much matter which. It's linked from onboarding, referenced in the system's README, even demoed in an all-hands. And still, a designer three months later drags a component into a file, needs to decide between two visually similar variants, and just picks one, because opening a separate tool, searching for the right page, and reading through it costs more in that moment than guessing does. The guide didn't fail because it was wrong. It failed because it was somewhere else.

This is worth sitting with, because it cuts against a common assumption: that documentation quality and documentation effectiveness are the same axis. They aren't. A team can improve the writing, add more examples, make the search better, and still see zero change in actual usage — because none of those improvements touch the real variable, which is whether the guidance is present at the exact moment and place someone is making the call. People build first and check documentation only when something already looks wrong, which means for most decisions, most of the time, the documentation is never even consulted. It's a rescue resource, not a decision resource.

The natural counterargument is that better discoverability should close this gap — a good search bar, a pinned link in the team's tool of choice, better onboarding that drills the location into people's heads. These help marginally, but they're solving the wrong layer of the problem. Even a perfectly discoverable wiki page requires someone to recognize, mid-task, that this is a moment worth pausing for and going to look something up. That recognition is exactly the thing that's missing under deadline pressure, and no amount of improving the destination fixes a habit that never begins the trip.

What actually changes behavior is documentation that shows up inside the tool, next to the component, at the moment of use — not a separate reference that requires a deliberate detour. A component description visible right in the Figma properties panel. Prop-level guidance rendered inside Storybook next to the live preview. Inline comments in the code that surface in autocomplete the moment an engineer starts typing the component's name. None of this requires abandoning the deeper reference material; it requires making sure the shallow, in-context version exists at all, because that's the version that actually gets read.

In practice this looks like layering rather than replacing. The deep usage guide can still exist for the genuinely complicated judgment calls — when to use a modal versus an inline panel, how to handle a component in a dense data context it wasn't originally designed for. But the entry point to that guidance should sit right where the decision is being made: a short line of context inline, with a link out to the longer explanation for the person who actually needs it, rather than the reverse, where the short answer is buried three clicks into a document nobody opens unless they already suspect something's wrong.

There's a real edge case worth addressing directly: not every piece of guidance compresses down to a tooltip. Some usage decisions genuinely need paragraphs of context, a table of exceptions, a rationale that took the system's owners real deliberation to arrive at. Trying to cram all of that into a properties panel produces a different failure — guidance so truncated it becomes misleading. The fix isn't to abandon in-context documentation for anything complex; it's to make the in-context version a faithful, honest summary with an obvious escape hatch to the full explanation, rather than pretending the short version is complete.

It's also worth noticing what in-context documentation does for maintenance, which is a secondary but real benefit. A usage guide that lives in a separate wiki can silently drift out of sync with what the component actually does, because updating the component and updating the wiki are two disconnected actions that different people remember to do at different times, if at all. Documentation embedded next to the component — in the same file, the same repo, the same design library — is far more likely to get updated in the same pass as the component itself, simply because it's sitting right there when the change happens.

None of this is an argument against writing things down well. Clear writing still matters enormously — a confusing explanation embedded at the perfect moment is still a confusing explanation. But clarity is necessary, not sufficient. The order of operations that actually works is: first solve where the guidance lives relative to the decision, then invest in making what's there as sharp and specific as possible. Teams that only ever do the second step, however well, keep getting a result that looks like a writing problem but is actually a placement problem.

If usage keeps drifting on a component despite what everyone agrees is genuinely good documentation, the diagnostic question worth asking isn't "is this written clearly enough?" It's "where does someone have to go, and what do they have to already suspect, before they'll ever see this?" Nine times out of ten, the honest answer reveals a gap between the tool where decisions get made and the place where the answer was written down. Close that distance and the same words that were being ignored in a wiki start actually doing their job.

The underlying lesson generalizes past any single component library: documentation isn't a deliverable you produce once and point people toward. It's a property of the decision point itself — either the right information is present when someone needs it, or it effectively doesn't exist, no matter how well it was written or how proud the team is of it. Measure documentation by where it lives, not by how good it reads in isolation, and a surprising number of "people just aren't reading the docs" problems turn out to be solvable without writing a single new sentence.