Friday, May 19, 2023

QA Your Docs: Final but often rushed step


Once you've written the docs, it's time to release. Right? No.

Other Technical Writer: But I double-checked the text and the graphics to make sure it looks good. 

Me: That's great. You looked at the docs and made the edits. Editing is step 4 in the general writing process. Every step in the writing process is crucial. But did you QA the docs? 

Other Technical Writer: QA? 

Me: Yes, did you QA?

Other Technical Writer: What do you mean by that? Do you mean I sent the doc to QA? 

Me: Well, you can do that and probably should if you have QA people. But did you QA the doc yourself, especially if you have the ability to do so. 

Other Technical Writer: Well, how do you do I that? 

Me: QAing your documents just means check to make sure the steps you wrote is matching the product is doing. In other words, does your document correspond to reality?

Often Overlooked Step

If we simply take the time and check to make sure the document is actually saying what the product is doing, then it might avoid dissatisfaction from our customers. How beyond annoying is it when the instructions are not only confusing but also don't correspond to the actions or parts of the product? This is probably why many chuck the instructions and try to figure it themselves. For a lot of things, someone can do this just fine. And the instructions are just stupid and useless. But what if those instructions are critical? And, if they try to do this themselves, they and others might get hurt–or killed–because of poor documentation. 

Instead of rushing things and slapping instructions together, let's simply take a little extra time to make sure the documents accurately portray the product. Faster isn't always better. It reminds me of this Scripture, especially the latter part of the verse:

"It isn’t good to have zeal without knowledge, nor being hasty with one’s feet and missing the way." -- Proverbs 19:2 WEB

A well written but inaccurate document is completely useless and should be tossed in the trash. A useful document has both accurate information and simple writing to clearly explain it.

How Do We QA a Document?

To QA a document, just walkthrough the document to verify what it says matches what the product actually does. When it doesn't, then fix the language or pictures until you go to the end.

If you feel it's too daunting to go through the entire document in one go, then you can QA a section after you finished writing and editing it. You can also go through the document in chunks until you're done. It doesn't matter how you do it. What matters is that you QA the document before you release it.

If we take this final, but needed, step then we won't miss our way.  If someone is preventing you from taking this step, push back if you can and tell them to wait until you're done. (Of course, the product and its documentation should go out the same time.)

It's better to take our time and put out documentation at a reasonable time, then rush it out the door and you'll have to deal with a bunch of problems after.

No comments:

Post a Comment