Validating Technical Documents

The extra step 
Even when you do a thorough needs analysis, create a solid document plan, and test a prototype before completing development, the job of validating technical content is not over. Subject matter experts will review the technical accuracy and completeness. That is an essential step, but still there is more.

If you are genuinely committed to making the content useful and accurate, you must test the end product on the people who will use it. With procedures, this involves a field test. With manuals, this involves usability testing. With a course, this involves a pilot.

Field tests 
All procedures should be field tested. If they are worth writing, they are worth getting right. This is especially important if the procedure could impact personal health and safety.

It doesn’t matter if the material was originally developed based on observation, the final draft needs to be validated. It also doesn’t matter if it’s been read by experts. Even highly skilled subject matter experts cannot remember everything involved in a physical task without a real-life context.

Many times I’ve taken a previously reviewed procedure, sometimes one in which people had a high level of confidence, and I’ve given it a field test only to discover it was missing important information. The reason is simple: the best way to make sure a procedure is correct is to watch someone performing it.

Field tests are most effective when they involve three people: an expert, a user and a writer. Under the guidance of the expert, the user does what the written instructions explain. The writer observes, takes notes, and asks questions to draw out as much information as possible.

In addition to identifying missing steps, a field test can give valuable clues about which parts of the task are most challenging. The writer will then have an opportunity to increase the effectiveness of the content.

Usability tests 
A field test is used to make sure the information is accurate. A usability test helps you make sure the information is easy to use.

In the early days of computers, software companies wrote their documentation based on how the programmers designed the code. This made the documentation easier to write, but it was of limited value in the real world.

People in the real world use software to complete tasks, so their user manuals need to be organized according to those tasks, not the interface. A thorough needs analysis at the start of the project helps reveal the different types of users and the tasks they typically perform.

A usability test needs to include each type of user performing typical tasks using the documentation as a reference. Three people should be present: an expert, a user and a writer. The writer’s job is to carefully observe how the user finds information, where they struggle, and whether the level of detail is helpful. The writer asks the user questions about the experience. The expert is on hand to answer any technical issues that might arise.

While this takes extra time and effort, it does a lot to improve customer satisfaction. For businesses that are committed to making sure their technology helps, usability tests of documentation are essential.

Course pilots 
A course pilot combines the objectives and methods of field tests and usability tests. A writer attends a class, looking for errors or omissions in the training content. At the same time, the writer observes the learning experience, looking for ways of making it even better.

I’ve attended many course pilots. They are always helpful for enhancing the effectiveness of training materials. The best way of knowing whether training materials work is to watch them being used.

It is also helpful to interview learners or ask them to complete a survey. Instructors also provide valuable feedback on the effectiveness of training materials. The course materials should not only help people learn, they should also help instructors teach.

When working on a technical document, it is easy to get lost in the words. But words are only written to help people do things. The only way to make sure those words are accurate and useful is to watch them being applied. Field tests, usability tests and course pilots are as important as any other stage in content development.

©Debbie Bateman 2019. Image purchased from Adobe Stock.

Leave a Reply