I'm passionate about getting high-quality feedback on my documentation. This is my profession, after all – I don't want to turn in shoddy work and I don't want customers to suffer with sub-par help. I'm happy to get whatever feedback I can; I'll even take spelling and grammar feedback and eat it like the delicious cookie it is. But as I've worked more and more on software development projects, I've set my sight on a new type of documentation feedback: user acceptance testing (UAT).
I don't think I've ever heard of a software team that performs docs UAT. But the more I think about it, the more it seems absurd. After all, we do software UAT to ensure customers have a chance to tell us whether our code meets their needs, has any bugs we missed, and how it can be further improved. This would also be valuable information for the documentation! And yet I've never heard of a place that does this. But why? Or better yet: why not?
Why UAT the docs?
If you don't agree with me that the docs need QA like the software needs QA, you can just get right out of here.
I'm kidding.
Stay.
Have some feedback cookies.
With QA, the same principle applies to the docs as to the software: you want to give your customers the best product you can. With software, that means designing simple, easy-to-use, error-free processes and systems that help customers solve their problems. With documentation, that means designing simple, easy-to-use, error-free documents that help customer solve their problems.
QA is an important first step for the software. However, taking the extra step to do UAT further helps the software by ensuring it meets the requirements of normal and expected use, and is stable and bug-free. If the customer needs changes, UAT gives them the opportunity to speak up about these needs.
With documentation, UAT would perform a similar function. The users run through the software updates with the documentation at their side. During this test, they confirm the documentation is usable, accessible, understandable, and navigable; answers their questions; and provides the information they need to do their work. Users can also alert the team to “bugs” (factual and mechanical errors), confirm the documentation meets the requirements of normal and expected use, and speak up about needed changes.
An added benefit to this practice is that it gives the users a chance to interact with the software and the documentation side by side, replicating their natural environment. This can help users be more successful in UAT overall, as well as to ensure that they know the docs are there as a first line of support.
When should you UAT the docs?
UATing the docs adds value to both the UAT process and the documentation itself. But when should you conduct docs UAT?
The best option is to conduct it in tandem with software UAT. As I mentioned above, this gives the users a chance to work with the two deliverables side by side, teaching them that the documentation is there as a first line of support. It also helps them to find problems in both the documentation and software (such as functionality that doesn't work as described).
That said, getting the documentation ready by the time software UAT begins can be difficult if your documentation team isn't large enough. If you can't get your documentation ready for UAT by the time the software is ready, consider hiring another writing. Alternatively, consider delaying software UAT by a day or two to make time for the writer to finalize the docs. You could also shorten sprints slightly to achieve the same flexibility.
Who should UAT the docs?
As with the "when" question, the answer here is “whatever you do for software UAT.” The users who conduct software UAT are the ideal audience for docs UAT. They're already in the process of checking whether the software works as expected. Other users wouldn't get as much from reviewing the software in a vacuum and their feedback will be less valuable without the comparison to the software.
How to UAT the docs?
This is the most complex question. After all, the specific way you perform a docs UAT should be similar to the way you conduct a software UAT, which can vary significantly across organizations. That said, there's some common ground. If you want to test the design elements of the software, consider breaking up the UAT group so that half get the documentation partway through UAT while the other group gets it immediately. The first group gives you insight on how well-designed the interface is while the second group – the one with immediate access to the documentation – provides overall feedback on both.
If you have a form for software UAT users to fill, have them fill it for the docs as well. They can provide any kind of feedback, right down to spelling and grammar, but they should focus on the usability, design, and navigability of the documentation. You can make the feedback optional, but if you've split the users into docs and non-docs groups, it will be more effective to require documentation feedback.
Want to learn how to integrate docs in Agile? Check out my eBook, “The 12 Principles of Agile Documentation.” Learn how the original 12 Agile principles apply to documentation, how to change your thinking to accommodate documentation, and the benefits you can get from bringing the docs into the fold.
