Write Answers, Not Documentation
In a recent discussion over on the Business of Software Forum a poster asked for help after noticing that a recent “improvement” in documentation has resulted in more customer support calls:
> A common advice for customer service requests is to improve the documentation, and this we have done for many years.
>
> But I’ve noticed that we’ve reached a new level of this. Improving the docs increases the number of service requests.
>
> Two reasons for this, based on feedback from customers seeking support:
>
> 1. Documentation is now so comprehensive that it is intimidating. People see a 1000 page manual and say “no thanks – I’ll just call customer support instead.”
>
> 2. Documentation has so much cool stuff described, that it makes people’s imagination stimulated and they start thinking of other, even more exotic stuff they want to do but can not figure out and start a service request for it.
>
> Thus, the common solution to service requests – better documentation – actually causes more service requests, not fewer.
One has to ask then what really makes better documentation. It would appear in the case of this company, the solution of increased, monolithic documentation was not better. So what makes better documentation? When creating content are you writing to provide evidence of how things work or are you anticipating questions and proactively delivering answers?
Users Want Answers
——————
Programmers are used to preaching that measuring lines of code is meaningless–it’s actually more valuable to have fewer lines of code assuming the functionality is not impaired. The size of documentation, however, is often times a measure of product robustness and capability. In the past I’ve even used documentation as a way to distract users from flaws within a product: “Look over here! See this big stack of manuals? Pay attention to this and forget about those bugs!” When training customers our documentation was always printed out and we always gave them multiple binders because we were trying to reinforce that our product was solid and trustworthy.
Unfortunately, as you might imagine, our documentation wasn’t written properly. Looking back on it we created (unintentionally) our documentation with size in mind, never answers. Our users ultimately wanted answers and they wanted them fast. Flipping through our documentation, however, made it impossible for them to achieve this so they often times turned to support for help.
When I hear people talk about the problem quoted above, I’m often times reminded of these experiences. A 1,000 page manual is useless if users can’t find what they need. Typically this is due to content not being written appropriately or if the navigation or search capabilities of the published form are lacking. Ultimately, if your user can’t find the solution in less than three steps I’d expect a support call or email, or at the very minimum a frustrated user asking for help on a public forum.
What Are You Gonna Do About it?
——————————-
Every customer support interaction is an opportunity to improve documentation.
I’ll say it again. Every customer support interaction is an opportunity to improve documentation.
Users always have questions that aren’t effectively covered in the documentation. Like taxes, this fact of life will always be with us and it is actually a good thing because it is representative of customer use. The more important question is what do you do with those questions after they’ve been solved? Do you use that experience as a way to head off similar questions from other users? Ultimately, users would **prefer** to **not** talk to you about their problems if they can easily figure out the solution themselves. How easy you make it is your choice, but to do it effectively you should consider how to continuously improve your documentation with “evergreen” content.
Think of your documentation as a tree. As it is published it’s like new spring growth. The leaves are green and the tree is happy. Over time your documentation tree needs to grow new branches and leaves because the old content becomes stale or doesn’t adequately address the needs of your users (would your users, in this analogy, be the birds and squirrels?). You need to prune the tree, fertilize and water it. Making it easy for the community to help in this process is critical, especially since most writing teams are understaffed and outgunned. Using the right tools and empowering the support teams and user communities to help you do this is both necessary and advantageous as it ultimately helps your company to create power users–engaged users who advocate for the success of your products.
When an author writes good documentation they ask themselves, “How will the user actually use this documentation to find the answers they need?” If they get it right and if the content is sufficient then there would be few customer support interactions. But when a customer is upset enough to call or email support, then you have a real-world feedback on how well your documentation answers that key question. This is extremely valuable information; indeed, UI developers pay good money to have user studies on their software before it’s released. Don’t squander this information!
Still don’t believe me? Consider this: the process of writing good documentation is much like making a good website. You don’t want to focus on throwing out information; you want to focus on how people will use it. Web developers have understood this for some time, just check out this chapter from the Steve Krug’s book, “Don’t Make Me Think“. There is an interesting synchronicity between product documentation and web content to consider, which only grows as documentation continues it’s migration to the web.
### Let us know what you think!
We’d love to hear your experiences with documentation especially as they relate to how you design, author, and deliver content so your users can effectively find the answers they need.
-->