Continuous improvement for user documentation
These days most software development teams are on board with the fact that software is never “done” until it’s retired. For one thing, the ecosystem in which your product or service is used is constantly evolving, so you need to keep it up to date with the latest platform changes, browser updates and security practices. Beyond that, the market is constantly moving, and being able to respond to new use cases and trends is essential if your product or service is to remain relevant.
It’s normal to see software development as a continuous cycle of development, release, feedback and improvement (ideally with plenty of automated processes to make that as consistent and reliable as possible).
But despite this culture of continuous feedback and improvement, I regularly come across software teams that think documentation is a fire-and-forget exercise. Once their user guides and reference materials have been published, they think the only thing left is to remember to update the docs when major new features are released.
Unfortunately, treating your technical documentation as a single ticket item in the product backlog misses the bigger picture: that your docs are part of your product. They form part of the user’s experience of your software. In fact, docs form part of the overall customer journey – featuring in prospects’ initial discovery and evaluation all the way though to influencing renewals and referrals. This means if you want to keep delivering value to your users, you need to apply continuous improvement to your docs as well.
Adding value with documentation
Having worked on a number of DevOps tools over the years, I’ve noticed several parallels between how software teams approach automated testing and how I like to think about technical documentation.
In the early days of building a software product, automated tests might feel like an unnecessary luxury (just like technical documentation). If you’re still validating whether your idea is worth pursuing or you’re experimenting with different architectures, then fair play to you. Spending time on any more than the most basic tests could well turn out to be a worthless investment.
At some point, however, you’ll reach a tipping point where investing in automated tests will save you more time (and money) than you would gain by not writing them. Putting the effort into writing automated tests not only reduces the time you spend on manual testing and results in fewer defects in production, but also makes your codebase easier to maintain and build upon in future. From that point, your automated tests become an integral part of delivering your software to your users.
The same is true for documentation. While it’s not essential at the very beginning, at some point it makes sense to invest in help content in order to reduce the burden on your support team and aid conversions. At the same time, the process of creating content encourages you to consider how effectively and efficiently your users’ needs are being met, often highlighting opportunities to improve the product design.
Documentation is an ongoing process
Returning to the analogy – writing that first suite of automated tests is just the beginning of an ongoing process. Obviously as your software grows, the functionality covered by automated tests will also grow. But that’s not all there is to it. As with the software itself, it pays to monitor how your tests are performing so you can use that feedback to refine and enhance your test regime. The practical advice ranges from implementing different levels of testing to analysing test metrics and structuring jobs to accelerate test results. By doing so, your code quality will continue to improve, in turn enabling you to deliver enhancements more frequently and thus improve user satisfaction and retention.
Again, the same is true for documentation. Once you’ve got past the initial hurdle of creating well-structured, user-centred content, it’s time to look to that continuous feedback and improvement loop to ensure your users keep getting the most out of your product. Below are five ways you can collect feedback and use that information to improve your docs.
1. Engage with customer support
Customer support cases are a great way to find out what your users are struggling with. That could be due to a gap in the documentation – perhaps a use case you hadn’t envisaged when designing a feature – or users failing to find the content they needed.
By looking through support tickets, you can identify the terminology your customers use to describe a particular problem. Some may also include the places they looked for a solution. In turn, you can use these insights to refine the searchability and browsability of your help docs.
2. Stay abreast of changing user needs
With the exception of games, most people don’t use software for the sheer pleasure of it. They use it to meet a need or solve a problem. Along with the world around them, your customers’ context of use is constantly evolving. Staying abreast of how your product is being used and updating your content to reflect those use cases is essential if you want to keep meeting your users’ needs.
As well as reviewing support cases (see above), it’s worth keeping an eye on discussion boards and social media to find out how your customers (and potential customers) are using your product. Of course, any insights you glean are also worth sharing with the product manager and development team, as they could inspire a new feature or a better way to position the product.
3. Solicit direct feedback
Just as with your software, there are several ways in which you can collect direct feedback on your technical content. Thumbs up/down widgets on individual content pages are a common starting point. I like to see these coupled with a free text box to give users the opportunity to add more details if they wish. Depending on your target audience, it can also be appropriate to include links on your documentation pages so that users can add suggestions to your issue tracker or edit your content directly in GitHub.
Given that your docs are part of your product, there’s every reason to include documentation in existing product feedback channels. Adding a few questions to a product surveys or customer engagement calls takes little effort and can tell you what users find helpful as well as what they feel is missing. Likewise, usability sessions can provide both direct feedback on the documentation (in those cases where the participant chooses to refer to the docs) and indirect feedback with insights into terminology and mental models.
4. Monitor your metrics
Metrics for documentation can be a touchy subject, as they are usually motivated by questions along the lines of “prove that the docs save us money”. Leaving those kinds of metrics to one side, I believe it is worth analysing whatever metrics your docs tool provides – even if it’s just total page views and most common search terms.
By looking into this data, you might be able to identify the areas of the product that users need most help with. This in turn can prompt further user research into potential sticking points or justify creation of additional content in other formats (such as screencasts or videos) to make the process more accessible.
5. Explore observability for docs
Page metrics on their own are a limited tool, but what if you could combine this data with task completion rates and other user behaviour? That’s the kind of documentation observability that Fabrizio Ferri Benedetti proposed in his recent post on documentation observability.
Observability in software products and services is still a relatively new trend. If your development team are starting to explore this area, why not try bringing documentation into the scope from the start? If your software includes embedded assistance or links to the documentation in the UI, that could provide a way in.
Adding value with technical documentation
Just like automated tests, creating technical documentation is an investment in your product. By providing well-structured content that addresses your users’ needs, you help your users get the most out of your software, increasing the likelihood that they’ll keep using it and recommending it to others.
To ensure your documentation keeps delivering value, you need to apply principles of continuous improvement – just as you do with the software itself. Observing how your product and your docs are used in the real world provides valuable insights that you can use to improve your content and thereby enhance your customers’ experience.
