I once worked with a team of very talented software developers. They created a very nice and well engineered software product. The product’s documentation was equally impressive. However, the documentation was hidden within the product itself. Key terms and concepts were not defined. The screenshots were outdated (from 3 years ago). As a result the team received a huge amount of support tickets.
The documentation wasn’t wrong, it was just not very useful.
The biggest gap between a set of technically accurate pieces of documentation and a set of pieces of documentation that are actually going to be useful to someone is a gap that most teams struggle to bridge. I have found that the fastest way to learn to write better documentation is to study examples of documentation that are well written. I store away lots of examples of good documentation and study them from time to time. I find that having a repository of such examples is very powerful.
The thing about learning from examples
It is common for architecture students to travel to examples of architecture before they start to design. There is something that one can learn from examples of well-designed buildings that one cannot get from blueprints and written descriptions. Documentation is similarly easy to write very poorly. So studying examples of good documentation is likely to study things that will be of far greater value to you than a content review or audit.
You can learn things that aren’t immediately obvious to you when reading about good technical documentation examples. When organizing a help center, one of the things that you should do is anticipate the user’s mental model for using a product. For example, instead of having a separate section in your help center for your FAQ’s, anticipate the questions that your users would ask before they even ask them. The API reference for a system is like a well-organized hardware store. All of the things that you need are stored on the shelves in an organized fashion, and you can find what you need without having to wander around. This isn’t an accident. The writer of the API reference made a number of deliberate decisions, and those decisions were made because the writer had a good understanding of the audience for the API reference, and because the writer cared about that audience.
But do you understand your users as specifically as this example does?
What strong documentation actually has in common
The examples of documentation that get shown off usually have a few things in common. I have been studying lots of examples of documentation for years, some of which are brilliant, and others that are just depressingly bad and make me wish I had closed the browser tab. However, all examples of documentation that work have the following things in common.
- They’re written for a task, not a topic. Good docs don’t just explain what a feature is. They walk you through what you’re trying to accomplish and then get out of the way.
- Navigation is treated as content. How information is organized tells users what the team thinks matters. Buried navigation is a signal that the writer, not the user, organized the content.
- Terminology is consistent and deliberate. Not every team agrees on this, but the ones with the clearest docs have clearly agreed on what to call things — and then actually stuck to it across every page.
- The tone matches the context. A quick-start guide for a developer tool shouldn’t read like a legal brief. Strong docs adjust register without losing accuracy.
Most of these points are old hat for documentation writers, but seeing the documentation of good and not-so-good systems side by side and in the same context is a very different thing from reading about them.
A quick comparison worth thinking about
Here’s a simple framework for your team to evaluate their documentation. They might discover some painful realities about their documentation, but it will be worth it in the long run.
| Documentation quality | What it looks like in practice | Common outcome |
| Weak structure | Topics dumped into long pages, no clear entry points | Users give up and email support |
| Inconsistent terminology | Same feature called three different things across pages | Confusion, erosion of trust in the docs |
| Task-oriented writing | Steps organized around what users are actually trying to do | Faster onboarding, fewer repeat questions |
| Maintained and versioned | Docs match the current product, with change logs | Users trust and return to the documentation |
Something I keep coming back to
Again, the worst part is that we mostly already know. We’re aware our documentation is out of date. That it’s inconsistent. That we wrote it for an internal audience that has long since changed.
Taking occasional breaks to explore fresh lifestyle inspiration and everyday ideas can also help teams return with a clearer perspective when tackling long-term improvement projects. There’s a reason that things continue to deteriorate as they do. Documentation improvements seem to be an abstract and low-stakes task until things break in spectacular fashion (support tickets flooding in, a churned customer leaves feedback mentioning your terrible docs).
The problem with documentation is that it tends to fall by the wayside until something breaks in a very public and very costly way. Then there is a mad scramble to fix the problems that have arisen and to prevent similar problems like that in the future. This can be a very overwhelming process for any company to go through.
Studying examples of good documentation is a whole lot more valuable than reading an audit of your team’s documentation. The audit will show you what’s wrong with your documentation. An example of good documentation shows you what is possible with good documentation. That’s a lot more motivational to most people.
How teams can actually apply this
The real question is how you can apply these lessons to your work. This is a practical guide to studying documentation examples, so we can get started here.
- Pick two or three documentation sites you genuinely admire. Spend thirty minutes reading them the way a user would, not a writer.
- Make a list of specific decisions you notice: heading structure, sentence length, how they handle warnings or edge cases, whether they use numbered steps or prose.
- Bring those observations to your team and map them against your own docs. Not to copy, but to identify gaps — the places where your instincts diverged from what clearly works.
- Pick one gap to fix. Not five. One.
The biggest mistake that teams make when they try to improve the documentation is that they try to overhaul the entire documentation set at the same time. They fail. When you have a large set of documentation, it is impossible to make improvements to the entire set at once. Each piece of the documentation must be improved one at a time. When you are working on a single piece of documentation, you can improve it and then move on to another piece of your documentation. When you have improved a section of your documentation, you can shape the changes that you have made to that documentation based on the behavior of your users. This is not possible when you are trying to make a large overhaul of your documentation. You may have the best of intentions but the fact is that when you try to make a large change to your documentation, you are likely to fail.
The part most teams skip
First off, I guess it’s sort of laudable that your documentation is so woefully inadequate. If it were better, you’d know by now, and you’d be taking steps to ensure that ensure it continues to be adequate. Even small steps can be better than nothing, because – let’s be honest – large overhauls of documentation fail spectacularly after the first sprint. But small, targeted fixes can make a huge difference.
When a team is documenting a product, what they are doing is more than just documenting the product. They are making a statement to users about how much they care. And not just about writing down information about the product that users might find useful, but also about thinking about the users enough to make a few assumptions about where they would get stuck, and then including information in the documentation to prevent that from happening. In short, good documentation is a rare thing, because it is a huge pain to write and maintain. But it is worth it. It makes a huge difference and it tells users that you care about their time, and that you are trying to help them.
