Community

Thoughts on Docs – So what if I have bad documentation?

Share this post:

bluemix_logo_hero_100For many teams, documentation is an afterthought: it’s an item to be checked off the list once a release is finalized. At best, updating the documentation is an item in the team’s backlog for the writers to handle, and at worst it’s “something we’ll get to eventually, but we can’t prioritize it right now.”

Of course, docs vary greatly for different teams and products, but every team needs good docs. I’ve been a product manager for Bluemix documentation for over a year now, and I’ve learned a thing or two about documentation along the way. Here are my thoughts on how bad documentation hurts your product and some ways to create high quality documentation.

Why make it a priority?

1. Bad documentation causes churn. (See this Wikipedia article on churn rate)
When I mention bad documentation, I mean docs that are out of date, overly complicated, or simply wrong. When your customers come across bad docs, especially early in the adoption lifecycle, their tendency to leave the product altogether increases dramatically. This is especially true in the digital self-serve world in which we live today. If you have bought into the idea that people should be able to use your product with little to no interaction from your company, giving them the resources to do so is paramount to their success and satisfaction.

2. Bad documentation costs money.

Aside from the money that’s lost through customer churn, having bad documentation affects users in three other areas of the six universal experiences. In the “discover, try, buy” phase, if users are unable to try out your product in a way that’s meaningful to them, there’s no way they will pay for anything. Giving them the tools to help with trying something out should include documentation that makes understanding your product as simple as possible. Next, in the “leverage and extend” phase, users who want to use more of your product will have the help they need to figure it out, meaning they won’t pay for more. Finally, in the “get support” phase, any time a user is forced to solve a problem that could be solved through better documentation by contacting support, you’re costing yourself money unnecessarily.

3. Bad documentation ruins the perception of your product’s quality.

Quality is a multifaceted concept, as I’m sure you are already aware. Quality encapsulates many things, including uptime, response time, resilience, user value, etc. All those aspects of your product must adhere to similar standards for it to be regarded as high quality. Take a diamond for example. If there’s a blemish on a single face of a cut diamond, it’s immediately graded as lower quality and in some cases thrown out altogether. Documentation quality is one of the faces of your product. Don’t let it slip through the cracks.

Documentation Best Practices

1. Don’t impose your own understanding of the product on your customer.
This is a danger to any part of the product team. For documentation, it’s easy to trick yourself into believing that a concept is too simple to need explanation or that a topic is easy to find in your content collection. Just because you have known and understood something for a long time does not mean that your users will. I’m not suggesting that every single detail needs to be expounded upon, but given the appropriate feedback mechanisms and validation about your content, you should be able to divorce your mental model and assumptions about the product from the actual needs of the people who are reading your docs and using your product.

2. Put writers on your development teams.

One of the main reasons I’ve found documentation to be out of date is that development and writing teams are completely separated both physically and organizationally. In the world of continuous delivery and constant iteration, this cannot be the case. Regardless of the development process your product has adopted, the people responsible for writing and maintaining your documentation should be working hand in hand with your development team. Not only does this give your writers a better sense for the changes they need to be prepared for, they’re also better able to get direct input on the content they’re creating.

3. Stay in touch with the support team.

Support teams have a great sense for what is and isn’t working for your product. Not only can they provide direct feedback for your content from customers, you can also help direct them to the appropriate docs to address problems for customers. The more documentation and support teams can come together, the easier both jobs will become. You may find that a certain area of your product continues to get a lot of attention from support, and adding a topic in your docs could help to keep users off the phone and back to being productive.

4. Constantly seek to understand your customers.

There’s nothing like direct feedback on your product from people who are using it when it comes to creating content for them. Having empathy for the people you are creating content for as you create it is invaluable. If you can’t visualize how one of your customers will find and use your content, you run the risk of working in a vacuum and perpetuating unhelpful content paradigms.

There are many ways to get direct user feedback on your documentation, and it doesn’t really matter how you do it. For example, the Bluemix docs do this a couple different ways. First, we use a plugin called Usabilla that accepts user comments and feedback directly, and creates an issue in our backlog. We also host much of our documentation in GitHub, so users are able to view the source and create pull requests to change the content directly. What really matters is that there’s an accessible avenue for feedback on your docs and that you use it. Just as I mentioned earlier about getting in touch with customers (a very direct, pointed approach to feedback), having digital methods of feedback allow a much greater number of users to respond directly to you. While keeping in mind each comment on its own is a single data point in a cloud of opinions, incorporating this type of feedback can immensely impact the quality of your documentation.

5. Test your docs yourself!

Finally, and most importantly, use your documentation. Walk through it yourself or with your development team to see if you can accomplish the tasks or understand the concepts you are describing, and watch out for areas in which you’re making assumptions or cognitive jumps. If you do this regularly enough, you’ll find that your docs will become more user friendly and complete.

These are just a few of the concepts I’ve found to be most helpful for our docs teams. Documentation doesn’t have to be groan-inducing, and if done right, it can even be delightful.

Happy writing!

Offering manager - IBM Cloud console

More Community stories
May 1, 2019

Two Tutorials: Plan, Create, and Update Deployment Environments with Terraform

Multiple environments are pretty common in a project when building a solution. They support the different phases of the development cycle and the slight differences between the environments, like capacity, networking, credentials, and log verbosity. These two tutorials will show you how to manage the environments with Terraform.

Continue reading

April 29, 2019

Transforming Customer Experiences with AI Services (Part 1)

This is an experience from a recent customer engagement on transcribing customer conversations using IBM Watson AI services.

Continue reading

April 26, 2019

Analyze Logs and Monitor the Health of a Kubernetes Application with LogDNA and Sysdig

This post is an excerpt from a tutorial that shows how the IBM Log Analysis with LogDNA service can be used to configure and access logs of a Kubernetes application that is deployed on IBM Cloud.

Continue reading