Many times when I’ve had to visit product documentation for clarity or an introduction to a product, I ended up spending far more time than I intended. Why? Because finding the information I needed was unnecessarily difficult.
Some documentation does a great job of explaining all the features of a product. But that’s all they do. It’s obvious they didn’t consider how users might actually interact with the product. Their goal was simply to write as much product information as possible, without bothering to ask how the user might need to use their product or how that should influence the design and development of the documentation.
On the other end of the spectrum, I’ve seen documentation that focused on users, but did it poorly. These docs often skimped on critical details. Important reference materials were missing. I once had to dig through a GitHub issue to find an answer that should have been right there in the docs.
Sure, navigation was clean and beginner guides were well done—but once you moved past the basics, there was very little value for experienced users who needed more technical depth or architectural insights.
In the first case, the writers probably thought: “Let’s list all our features so the users know everything about us.” But their navigation was weak, and the language they used was overly technical or niche.
Importantly, they ignored the core principle that technical writing is about breaking down complex ideas, not stacking them. But of course, one can’t expect much from an unstructured information wall attempting to play the role of documentation.
In the second case, the writers understood the importance of considering users, but didn’t identify which users. They treated all visitors the same, tailoring their docs to only one or two user types. Everyone else had to scavenge for information elsewhere.
How I would recommend solving either of these issues
First, writers need to understand that the first step to writing effective documentation is understanding the product. You can't help people effectively understand what you don't understand yourself.
The next step, however, IS NOT writing, nor is it deciding what documentation framework to use. The ideal next step should be understanding your users. This is the part where you do enough research about the prospective users of your product. Here, you need to take your time to develop user personas. Ask questions like:
- Who is visiting my docs, and what do they need?
- Who needs this specific feature, and how can I help them find it easily?
- How do I support different user types within a single documentation system?
These questions matter. They help shape how your documentation actually serves people.
Only after understanding your users should you start thinking about frameworks and structure. As Fabrizio Ferri-Benedetti pointed out in a blog post, documentation frameworks are just content types. What matters more is the people you're creating that content for.
Documentation must be tailored to suit users' needs. I believe this is an absolute truth.
Top comments (0)