Documentation deserves the same design process as your product

A client hired us to update their documentation. The request to rewrite a series of pages seemed straightforward, but a larger issue loomed within the accumulated pages, unseen by their team but felt by their users.

As we worked through discovery, it became obvious that the writing was only part of the problem. The client's site had grown organically over the years. New pages were added whenever someone had something to publish. Different teams owned different sections. Navigation favored the company's internal organization over how customers used the product. Together, these decisions created something that was confusing to use and difficult to maintain.

That client wasn't unusual. I've seen the pattern enough times now that I expect it: teams assume they have a content problem because content is the visible part, so they rewrite the confusing pages, add the missing ones, and reorganize the cluttered sections. Sometimes it helps. More often it improves the writing without fixing the experience.

That realization changed my perspective. I stopped thinking of documentation primarily as content and started thinking about it as a product experience.

Documentation deserves design discipline

When we run strategy for a client, we don't jump into writing. First we figure out what's actually broken. We talk to users, we test our assumptions, and only then does anyone commit to a build. Each step reduces guesswork and makes the result better for whoever uses it.

Documentation rarely gets that treatment, even though information architecture, governance, and research shape whether it succeeds long before anyone writes a word. Skip that, and you get what this client had: a site nobody designed, only added to.

The work starts with users

User research is where my design planning starts. I start with the users, because they're the ones who know where a product really stands. While an executive can explain what it's supposed to do, users know what it actually does. They'll show you the workaround they came up with when a real path is broken.

Those conversations almost always redirect a project. Once you understand how people interact with a product, decisions about navigation and structure follow what you observed instead of what you assumed.

Documentation now serves two audiences

Something else has changed over the last few years: documentation is no longer written only for humans. It also feeds the AI systems answering questions on our behalf, whether that's ChatGPT, Gemini, Claude, or an internal coding assistant. Those systems rely on the knowledge we've published, and when that knowledge is incomplete or inconsistent, the answers degrade accordingly.

What I find encouraging is that this hasn't required a completely new discipline. The practices that have always produced good documentation also happen to produce documentation that AI systems can understand. Clear information architecture, well-defined topics, semantic structure, and consistent ownership benefit both audiences.

Build something people can experience

With this client, we made one decision that changed the conversation. Instead of putting recommendations in a slide deck, we built a working prototype. It existed to show what this documentation could look like when designed with purpose from the start.

Navigation followed user tasks instead of internal departments. The structure had a logic behind it. Content lived in Markdown rather than buried under layers of presentation markup, which meant a machine could read it cleanly. Every section had an owner, so it was clear who kept it up to date.

When we placed that prototype beside the client's existing documentation, something interesting happened. We stopped debating opinions. People could compare the two side by side, and the conversation shifted from preference to evidence.

I've found that's true of product work in general. A prototype gets a reaction. A recommendation gets a nod.

Design it the way you design products

That project didn't change how I think about documentation so much as confirm something that had been true for a while. The fix for most documentation problems is design, not another rewrite.

Writing matters, but design is what determines whether it works. Research comes first, then information architecture, ownership, content strategy, and iteration. Effective documentation applies the same discipline as product design, understanding users and designing with intent. And, like the product it documents, it evolves in response to user feedback.

Customers don't separate your product from your documentation. They move through both as one experience. The longer I do this work, the more convinced I am that the teams building it shouldn't separate them either.

Talk to us about designing your documentation.