In my previous post, The key to writing good documentation: Testing your instructions, I noted that although quality assurance teams can review documentation, my experience is that they review it like a robot. They don’t comment qualitatively, noting whether something is clear or not, whether the message is on target, whether the tasks represent the user’s workflow and business needs. Instead, they analyze the steps strictly for accuracy (which does have benefits, of course).
However, I’m starting to think that my approach with documentation has been too laissez-faire in terms of its insertion into the engineering process. Engineering code goes through rigorous review by QA and product managers weeks before release, but most teams are happy to move documentation outside of this process. Just having the doc finished is enough. If done, they can “check a box” and include it in the product, without reviewing it more than cursorily.
But maybe this approach is wrong. If you insert documentation into a similar workflow as engineering code, you would submit the documentation to QA in time for review. This means you would need to finish the documentation usually two weeks before the release cycle.
This can be difficult since it’s hard to write documentation when code is still developing. A lot of times features aren’t yet fixed, so it’s hard to create documentation for them. Still, the sacrifices necessary to insert code into QA’s review process might be worthwhile, since the benefits would outweigh the added pressure to finish the doc early.
Let’s say that QA cuts you some slack and allows you to submit doc to them one week before release. If so, QA will need some clear guidelines on what they’re supposed to test. QA might test the following:
If you don’t give QA guidelines, they won’t know what to test. Just as QA needs to know what the system is designed to do in order to test it, QA needs to know what the doc is designed to do in order to test it. The poor reviews I’ve gotten from QA in the past were probably because I didn’t give them any guidelines about what to check.
I wouldn’t task QA with qualitative assessment of documentation. For that, I would assign product marketing or product management. A product manager or marketer can review the documentation with the following questions in mind:
Product managers and marketers do wonderful jobs assessing the doc content qualitatively. But they don’t necessarily have the time or expertise to conduct the technical assessment. QA is much better for that. At the same time, QA is usually poor at qualitative assessment.
The pros of inserting documentation into an official engineering review process are as follows:
The cons of inserting documentation into an official review process are as follows:
Although I sometimes like having doc be outside the engineering review process, I’m going to experiment with inserting doc into the official code review process, split between both QA and product management. I’m confident that if I give both QA and Product Management or Marketing clear guidance on what to test, these internal groups can provide a lot of worthwhile and helpful input for improving the documentation.
Inserting docs into the code review process will also help me avoid time crunch situations in which I’m cramming to finish the docs before release, and everyone is too busy to review the help in any detail.
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.