Technical documentation is an integral part of a software product and must be regarded as such. We all know what happens after a software feature has been developed: it goes through a code review, and then it is thoroughly tested by a QA team. Before each release, the entire application undergoes multiple tests.
Technical documentation goes through a similar process: with each update, it passes several rounds of reviews. However, what about testing software documentation as a finished product? Among various roles in a project team, who is responsible for doing that?
If you google the term “documentation testing”, you will get tons of links to software testing websites where this activity is listed among many other QA engineers’ tasks. Let us consider this description, for example: “The documentation can be tested in a number of different ways to many different degrees of complexity. These range from running the documents through a spelling and grammar-checking device, to manually reviewing the documentation to remove any ambiguity or inconsistency”.
Documentation testing activities generally fall under the following major categories based on the types of testing:
- Technical accuracy testing
- Functional testing
- Usability testing
Functional and usability testing of documentation have already been discussed on Informaze in detail. Firstly, here is a great checklist of the ways documentation functionality should be verified in the pre-publishing phase. Secondly, in one of the previous posts, we discussed usability testing as an integral part of InfoDevs’ work aimed at producing a quality deliverable. These TechComm 101 practices are an indispensable part of documentation development process.
In contrast, technical accuracy testing requires access to application and at least some specific technical and domain knowledge. Moreover, the higher complexity of an application, the harder it is for InfoDevs to provide this kind of documentation testing.
Therefore, technical accuracy testing is often considered to be a QA engineers’ domain that involves verification of the following items:
- Technical accuracy of explanations and described behaviors
- Absence of missing steps in procedures
- Validity of screenshots, their up-to-date status
- Correctness of the names of UI elements in documentation, their compliance with the actual UI
But when deadlines are pressing, release date is near, and “nobody reads it anyway” mantra is remaining popular, the chances are high that verification of technical accuracy of documentation is left to the mercy of whoever has time to click through an application, verifying procedure after procedure. Do you believe that much will be corrected under such pressing circumstances?
In my opinion, since InfoDevs are responsible for overall quality of documentation, the responsibility for technical accuracy lies with us as well. At the very least, the “technical stuff is none of my concern” attitude should be unacceptable. It is worthwhile to go the extra mile gathering more technical and domain-specific information to be able to test documentation against an application. Yes, the learning curve may be quite steep, but better understanding of what and how your application does will help you avoid outright blunders and find existing drawbacks in descriptions and procedures. Thus, you can significantly improve documentation quality.
To be able to assure technical accuracy of documentation, InfoDevs should take the following steps:
- Get test environment
The first and most important step you need to take is to get access to a test environment—shared or your own. Sometimes, you can have both. For example, on a shared test environment, you can take screenshots with all needed components fully set up and displaying real-life data. On your own computer, you can install and click around whichever build you need without fear of deleting or changing important data.
- Verify technical accuracy
Getting access to a test environment enables you to see how an application really works. This way, you do not rely solely on interviewing developers and putting their exact words to paper, working as a typewriter. By clicking around an application yourself, you can verify that your topic provides correct technical information. The simplest example would be checking that the names of commands in your topic correspond to the existing UI names. A bit more challenging task is verifying that your code examples are correct and working. By the way, you might find things that do not work the way they are expected to, and in this way, you can be helpful to your team and bring additional value to your project.
- Test procedures
I think that it is impossible to create a correct procedure without reproducing the needed task yourself, step by step. In this way, you can assure that a procedure does not lack any steps. Setting up the needed component is often time-consuming, and you may require help from a developer, but it is worth it. When a procedure is documented, follow its steps once again. Look at your text through the eyes of a user. Can a task be performed if the user follows your exact words? Are the application behaviors clearly and fully described? Will the user have any difficulties in proceeding to the next step? Are there any “surprise” dialog boxes that may puzzle the user? You can try finalizing a procedure with less or wrong data in input fields, and see if any error messages appear. Perhaps, it is worth adding a note with explanation of some errors that can occur, or some preconditions that need to be met.
- Test screenshots
Screenshots verification should begin right at the moment when you are taking them. Pay attention to presenting all the information that is needed at a current step. Keep the same environment, application settings, input texts, and so on, so that your screenshots tell a consistent story that gradually develops throughout an instruction. Avoid situations when at the beginning, you are showing how to edit an Inputs folder, and then, on one screenshot, its name suddenly changes to Outputs—just because this screenshot was created or updated separately. By the way, be sure to verify that you are taking screenshots of the latest build where the feature is finalized. When all screenshots are in place, go through them without looking at the text. Check visual consistency of a topic or a section. In a series of screenshots of the same UI element, make sure there are no images that differ in color, theme, or size. For example, make sure that the same dialog box at different steps is not first looking bluish, and then grayish. Last but not least, you should pay special attention to blurring or avoiding sensitive information, for example, a license code to an application that your team is using.
I would like to conclude my message with the following statement: if we position ourselves as professionals of much broader competence than just being typewriters, we should assume responsibility for testing our deliverables. In this case, verifying technical accuracy, along with other types of documentation testing, is an important part of documentation development cycle.
What do you think? Please feel free to comment and add your own tips for documentation testing.