How to Ensure High Quality in Technical Writing
“Can you tell us more about quality in technical writing?” a reader asked yesterday, in a private email.
Here are my thoughts on the topic:
1) Quality starts with intra-team cohesion if you are working as a part of a technical writing team. If you’re a lone writer, this means you should either have your own guidelines in place or should be aware of the one used by your client. Without a documentation guideline to lead the way, the quality of deliverables is bound to suffer since every “new idea” will inevitably pull the project in a new direction. And you know how the food tastes when too many chefs add too many ingredients to a dish. Same story here with documentation.
2) Related to that, the writing team should have a clear division of labor with well-defined roles for team members. If one technical writer is also good at drawing illustrations, having her provide such graphic support will only enhance the quality of the end product just like having only one person (e.g., the lead writer or the doc manager) interface with the upper management would avoid conflict messages and promises.
3) Quality also depends on a very clear workflow. The documentation team (even when you’re working alone) should be aware of the steps involved from start to finish in the production of a document. Related to that, there should be a clear production schedule and it should be reported and enforced through regular department meetings.
4) Review cycle is a very important ingredient of documentation quality since it’s rare that the first draft of any document is good enough for release. Usually, documents go through at least two or three review cycles and I had those long stretched-out projects in which I’ve generated over 10 drafts, spanning over a year. For the review process to work, you need to commit the reviewers to a review calendar and follow it up religiously. Reviewers are usually SMEs, that is, very busy people. You need to keep tabs on them to make sure that the process moves smoothly, at an even pace. Last-minute correction and revision nightmares can be avoided if a commonly-shared review system is in place.
5) Peer review is another crucial ingredient of quality in technical writing. I’m always amazed at the things my wonderful colleagues find in my documents, just like I find similar things in theirs. An extra pair of eyes is always important to ensure quality. Don’t skip the peer review for personal reasons if you want to keep up with your quality commitments.
6) Lastly, I can’t emphasize enough the importance of education and training in our fast-moving technical communication field. This business of ours is changing at such a pace that I quit buying tech books a year ago since no matter which book I buy it’s bound to be at least partially out of date. (In case you’re wondering, I’m using wwwq.safaribooks.com monthly service to keep up with all the new publications in my field. Highly recommended.) A technical writer who does not renew herself and keep learning new techniques, platforms, and approaches, is a writer that might be without a job in the medium run. That’s why I firmly believe that the budget reserved for training is a “profit center” item (and not a “cost center” item) for organizations that would like to remain at the forefront of global competition.
There are of course many other factors that contribute to overall quality in technical communications but these are the ones that jumped to my attention as I was preparing this list.
How about you, dear reader? What do you think about “quality”? Which other factors would you bring up within the context of this conversation? You’re welcomed to share through the comments link below.
If at all possible, don’t proofread immediately Let your docs sit for a day or so to give your brain a chance to forget what you wrote. You’re bound to find a multitude of opportunities with grammar, sentence structure, flow etc.
One of my favorite tricks especially with Word docs is to make all the text red and I proofread it convert it back to black. This allows me to focus on one sentence at a time as well as providing me a bookmark of sorts in case I have to leave the document and come back to it later.
I should have proofread my first post. :o)
Sandy, this is a very interesting technique. I’ve made a note of it. Thanks for the feedback.
‘Insure’? I suspect you meant ‘Ensure’, although i ‘d agree that quality comes at a premium!
But of course 🙂 Thanks for catching the error. Corrected right away. Many thanks! Ugur
I completely agree with all six points above! Well done! Consistency is key, the hard part always seems to be agreeing on who should do what consistently… We leverage checklists on every document we touch to ensure quality and consistency. We also leverage the same checklists to perform peer reviews on each other’s work.
Although it is sometimes difficult to make the case for quality, if you call it “risk mitigation” and/or “content validation” work, then people tend to have stronger support.
Jason, thanks for the excellent ideas. I loved attaching the “risk mitigation” and/or “content validation” labels to the documentation QA process. Will try to adopt it for my own workflow. All the best, Ugur
I have a question. How would a lone writer complete the review process in a start-up? To be more specific how can one do a Peer review?
Rekha, thanks for writing. I’m trying to understand your specific situation. You’re a “lone writer” but you work for a “start-up company” (by telecommuting perhaps), is that it? For peer review you need to find another technical writer, if not in the same company then perhaps a writer friend that you can trust; someone whose judgement and professional background you respect. But if you can’t find any such person, then you can ask a SME (Subject Matter Expert) or a developer to have a look at what you’ve written as well. But that would be more like a regular content review than a “peer review”. Those two kinds of review overlap to a certain extent but they’re not the same. Grammar, expression, and formatting errors, for example, can be detected much better by your writer peers than SMEs or engineers.