Does Your Documentation Suck?
I’ve been browsing a lot of online documentation lately and in a past life I spent an enormous amount of time worrying about how my users were interacting with documentation. It never ceases to amaze me how bad most product documentation is, especially when the documentation is published in a half-measured attempt on the web. Do companies not realize the negative effect poor documentation, both content and presentation, have on their users?
There are really three things that can impact whether your users find your documentation useful:
- Quality and Completeness of Content
- Search, Browse, and Read Experience
- Interactions and Content Freshness
Quality and Completeness of Content
Suffice it to say the first bar is a fairly obvious one. You need good, well written content. That content needs to be complete. It needs to cover the product not only from a serial, narrative point of view but also from the point of view of a user in trouble. This is step one, and its something that technical communicators are good at, assuming you can find one that understands their role as a conduit between developer and user. They must proxy the users needs into the development of the product and they must communicate clearly so that users can understand what it is they’re using and work their way out of jams.
This shouldn’t be surprising.
Search, Browse, and Read Experience
Documentation presentation needs to account for the motivation of the user. Users are sometimes looking for specific answers and sometimes they are trying to do broad based learning. These are very different motivations and they may lead your user to enter your documentation from different sources.
For example, when I have a problem with a product I almost always turn to Google. Google’s search will typically lead my to the answer and at the very minimum it will help me gauge whether my problem is isolated or wide spread. You should expect your users to use Google as a tool to find answers to problems they might have with your product or service. The implication of this is simple: if you don’t publish your documentation to the web in a form that is easily indexable by Google you’re doing it wrong.
Sometimes users want to understand the product in a more general way. They want to browse documentation taking in more than an answer to a specific problem. When I’m learning about a new product and want to take the time to read I might still enter through search, but its more likely that I will begin browsing documentation based on entry points given to me. For example, a series of tutorials or a getting started section. From there, I’ll selectively jump around following topics where they may lead me. For you, the documentation publisher, this means you need to write your documentation with natural entry points, natural learning paths, and lead the user where you want them to go. You should not expect someone to read your manual in a serial fashion, from start to end, especially on the web. Furthermore, for those users that still enter their browsing experience from the web, make sure your entry points are visible to Google with keywords that are likely to be used. SEO isn’t just a tool for marketers, its a way for you to bring users into your community in a controlled, orderly way before they have a problem.
Finally you must considering the experience of the user while reading your documentation. Design matters, and presenting your content in a visually appealing way isn’t rocket science. Take the time and spend the money to get it right, it isn’t that expensive and looks do matter. Furthermore, make sure you’re giving the user natural paths to follow while they are reading. You know how the content is structured, but that doesn’t mean you should force the poor user to continually go back to the table of contents to find their next topic.
Interactions and Content Freshness
Stale content is a good way to ensure a grumpy user. Don’t let your content get stale, and make sure that if you’re product has multiple versions deployed that the documentation is available for each deployed version. One good way to get your users involved with your company is to make it very easy for them to provide feedback and contribute to the documentation. Furthermore, this helps your content stay fresh for users who follow on later. Providing interactivity for end users, so they move from passive readers to active collaborators is valuable to you, your business, and your user community.
Let us know what you think!
We’d love to hear your stories about good, bad, and ugly documentation. Who does it right? Who does it wrong? Leave a comment and let us know!
-->