Lead Writer: Kieran Morgan | Peer Reviewer/s: Felicity Brand, Steve Moss | Managing Editor: Kieran Morgan
This chapter emphasizes the critical role of validation and testing in technical documentation. It details various methods like fact-checking, testing, user acceptance testing (UAT), usability testing, and informal usability testing. These are all important steps for ensuring technical accuracy and effectiveness in documentation. The chapter aims to equip technical writers with the necessary skills to create not only precise but also practical and user-centered documentation.
 Who Should Read This | |
| • Aspiring Technical Writers • Beginner Technical Writers • Cross-Domain Professionals | |
| Table of Contents: Technical Writing Process | |
| Previous: Chapter 20: Review Draft | Next: Chapter 22: Translation Theory |
1. Introduction
Let’s say you’re a scientist on a voyage of discovery within your field of expertise. Maybe you’ve dreamed up a new molecule that you think is going to rid the world of some terrible disease. You’ve done the research, read the academic papers, and worked through your equations. All the modeling shows you’re on the right track.
But you haven’t yet tested your theory in the real world. Is your theory valid? Not yet! That’s not how the scientific method works. As a scientist, you can’t claim your theory is effective until it’s been rigorously tested under experimental conditions. Similarly, in technical documentation, validation and testing are critical phases where the “theory” of your documentation meets the realities of the product and the user experience. It’s not just about technical accuracy; it’s also about effectiveness. Does your documentation enable your audience to successfully complete tasks?
In Chapter 21: Edit Drafts, we touched on these concepts as vital levels of editing in technical writing. Validation and testing are not stand-alone processes but integral elements of the comprehensive review process outlined in Chapter 22: Review Draft. The sequencing of these steps—when they’re done in practice—is illustrated in Chapter 22: Review Draft | 2. [Theory] Write Review Update Process.
In this chapter, we explore in depth the methods of validation and testing for technical documentation. These methods vary in complexity and cost, and their application should be strategically timed. Some come before the subject matter expert review, some after, while others can be scheduled at any stage. Your judgment in choosing the right method for your documentation will significantly influence its accuracy and user-friendliness.
Through this chapter, we aim to equip you with the knowledge necessary to ensure that your documentation is not only precise but also practical. It should enhance the user experience and contribute to the success of the product it supports.
 Insight |
| Add Value by Identifying Issues and Bugs Technical writers are often the first users of a product. While you’re testing your documentation, you may discover usability issues—or bugs—in the product you’re documenting. By providing this feedback to the developers—e.g., by logging it in their development tracking software—you can add value by improving the user experience before the product is released. Being a diligent and proactive member of the development team can be a career-enhancing move for a technical writer. |
2. [Theory] Fact-Checking
Fact-checking involves verifying technical facts against specifications, data, reference documentation, or by verifying them with key subject matter experts. For instance, you might confirm that a range of values described in a product’s user guide matches those in the product specifications. This is a crucial step for technical documentation, and it’s something you can easily do yourself by making sure you can validate every technical fact with reference to another document. Use this process to showcase your attention to detail and commitment to accuracy.
When Is It Done:
- Prior to review by subject matter experts, or simultaneously, if requesting validation of technical facts from experts.
3. [Theory] Testing
Testing is a process you can do yourself. It’s simple: see if you can follow your own instructions to operate the product (hardware or software) that you’re documenting. In doing so, you should also check that images or screenshots of the product match those in your document at each step.
This step is essential for product documentation. If you can’t follow your own documentation, how would a customer hope to do so? This process will also help you quickly identify whether your procedures are clearly worded and logically structured. It’s an easy and inexpensive way of ensuring high-quality documentation.
If it’s not possible for you to test your procedures yourself, arrange a walkthrough with a subject matter expert familiar with the procedure and observe as they follow your steps. This is useful when experts have access to systems and test data that you don’t.
As with fact-checking, testing is a rigorous and methodical process that draws on your attention to detail. You’ll need to step into the shoes of the users, which can be challenging if you’ve built up detailed product knowledge. For this reason, sometimes additional methods are employed that eliminate your biases and blind spots. These are discussed in the next section.
When Is It Done:
- Prior to review by subject matter experts.
| Insight |
| Try to Mimic User Behavior When Testing When testing a procedure, aim to mimic the behavior or use case of the user as closely as possible. Although it’s also helpful to test out of context, it’s more useful to approach testing from the user’s perspective. Challenge yourself to step into their shoes by posing questions: When would a customer attempt a particular procedure? What steps do they need to successfully accomplish beforehand? What would they do when confronted with the next screen? And so on. |
 Note |
| Check You’re Testing the Correct Software Version While testing, it’s essential to work with the correct version of the product’s software or firmware. This is particularly crucial in an Agile development environment, where features may be added or withdrawn at the last minute. |
4. [Theory] User Acceptance Testing (UAT)
In user acceptance testing, your documentation is tested as if it were software code. In this particular procedure, a testing team develops a number of test cases based on your documentation. They then attempt to execute these cases to see whether the documentation matches the functionality and user interface of the product.
The test cases may simply be a copy-and-paste of procedural text from the documentation, copied wholesale or broken into bite-size chunks. The testing team will then attempt to follow these instructions. If the instructions don’t produce the intended result, or if the pictures or text in the documentation don’t match the user interface of the product, they’ll chalk it up as a failure and pass it back to you for correction. Depending on the available time, the testing team may choose to test only a portion of your documentation, (such as the sections concerning the most high-profile functionality), similar to an audit.
The advantage of this method is that it removes the biases and blind spots you might have when testing your own documentation. It can be done in-house, leveraging your organization’s testing infrastructure.
When Is It Done:
- Following review by subject matter experts.
| What Does That Mean? |
| Test Case A scenario describing a set of steps with a defined start and end point, and an expected result. Test teams can use a test case, along with test data that is sufficiently representative of reality, to verify that a subject, such as a software application and its technical documentation, meets a specific requirement. |
5. [Theory] Usability Testing
Usability testing involves observing users as they attempt to use the product and follow your documentation. This is the gold standard for road-testing documentation. It eliminates any blind spots that you or an in-house team may have due to existing knowledge.
This type of testing is usually the domain of user experience (UX) designers, who test the usability of a product as a holistic package prior to launch, including documentation. Nevertheless, it’s worthwhile to understand how the process works, as technical writers should be integral to it. This is why we’ve included a brief description here. We’ve based our usability testing content below on Markel and Selber’s description in their book, Technical Communication.1
Usability testing can be quite elaborate, with realistic mock-ups of the product and its documentation set up, plus test participants recruited, akin to a scientific study. It can even be conducted in context—that is, at the place where users will be using the documentation. The study may be conducted by an in-house team or by a third party who specializes in usability testing.
The goals of the study and the evaluation guidelines should be defined well in advance. Test participants and observers are identified and recruited, and consent forms are signed. An evaluation form is drawn up so that observers can record any problems discovered during the test. A script and checklist should be drawn up to guide the sequence of events on the day, ensuring consistency among test subjects. On the day of the study, the observer should be neutral, asking open-ended questions, never prompting the user, even if they get stuck. The aim is to understand why the user got stuck and at which point.
After testing has concluded, feedback from the observers is compiled into a report and handed to the product development team. Both the product and its documentation are then updated based on the test’s findings.
When Is It Done:
- Following review by subject matter experts.
| Insight |
| To Test or Not to Test—Do the Benefits Outweigh the Costs? Usability testing is an elaborate and expensive affair. For this reason, it’s rarely used in practice.2 So, when should it be used? When the importance of the product and its documentation warrants it. Consider the consequences of users misunderstanding something. Could this lead to thousands of costly helpdesk calls? Is it for your organization’s flagship product, where errors could incur significant costs and damage your organization’s reputation and brand? Assigning a dollar value to documentation might seem like mission impossible, but it’s definitely within the realm of possibility. Consult Calculate Value in our forthcoming book, Technical Documentation Management—available online at Boffin Education—for guidance. |
6. [Theory] Informal Usability Testing
If formal usability testing isn’t an option, you can conduct informal usability testing—with much less cost and effort—by doing it yourself.
To do so, you’ll need to engage a proxy user within your organization, or within your social circle, if your organization permits it. This individual should have general demographics or a level of knowledge about the product or process that matches those of the intended audience of your documentation. In this informal process, you don’t need to do all the preparation of a formal study. Simply assume the role of an observer, and ask your proxy user to follow the steps of your documentation, noting down any problems they encounter along the way. As you repeat this process, you’ll discover many useful insights into the effectiveness of your documentation. Use a Review Log Template to capture and action the feedback.
Of course, this method introduces some issues that formal usability testing avoids, such as a smaller pool of testers, the absence of a scientific method, and potential biases as the content’s author. Nevertheless, it’s a quick and cost-effective way to gather valuable feedback on the effectiveness of your documentation. It’s ideal for small teams or those with limited time and budget.
When Is It Done:
- Either before or after review by subject matter experts.
| Insight |
| Having Trouble Following That Procedure? Try Talking It Through The talk-through approach is a useful method that helps eliminate bias. In this approach, the technical writer asks a test subject to describe their thoughts aloud as they work through the steps of a procedure. This can help identify any gaps in your instructions or false assumptions you might have made about the product or the user’s knowledge. The talk-through method is also useful during formal usability testing. |