- Books, Literature, and Writing»
- How to Write
Quality Assurance for Technical Writers
Webster defines quality assurance as “a program for the systemic monitoring and evaluation of the various aspects of a project, service, or facility to ensure that standards of quality are being met.”
As a technical writer, quality assurance must fit a broad range of undertakings. According to the Society for Technical Communication web page," The value that technical communicators deliver is twofold: They make information more usable and accessible to those who need that information, and in doing so, they advance the goals of the companies or organizations that employ them."
How the technical communicator goes about these tasks and does so successfully guarantees the quality expected of an organization.
To break the process down into manageable parts, we will discuss the following aspects of quality assurance for technical writing:
2. Copyright Basics
3. The Use of Style Guides
4. Peer Review
5. Documentation Control
6. Testing & Evaluating the Information
What to Avoid
Of top priority for technical editors is completely accurate information fashioned in such a way that it is easily understood by the average reader or user. Content must be totally precise and comprehensible.
A technical editor first edits a document for spelling/grammar, punctuation and organization making sure the document has fluidity meaning "flow". To assist in the editing process, a writer has some help from software tools, but writing well and being concise is a learned practice. Organization of material is key as well the use of lists, bullets and numbers which organize information in understandable and clear steps. The document should then flow from start to finish with the use of transitions and images that clarify purpose.
The technical editor sacrifices a certain amount of creativity for the sake of reader understanding when they reduce industry jargon, techie talk and the use of way too many words in their attempt to explain a process.
Let me explain - I once received a very wordy explanation and the crux of it was - "We are doing away with our PBX and switching to VoIP." I knew what this meant, but I couldn't imagine other receivers understanding this lingo. A clearer explanation would have been - "We are doing away with our old phone system and implementing VoIP. VoIP stands for voice over Internet protocol meaning instead of traditional telecom wiring your voice communication will now be transmitted over the Internet." You would then go on to explain what this means to the user which may include training and tutorials, but if the reader does not understand the first sentence or two, he or she may not continue to read what is potentially important information about a new process that will certainly affect them on a daily basis.
Next, if input is coming from various sources, it is important that it be synchronized and formatted according to company organization standards so the document has a uniform feel. Synchronizing information across a company or organization structure is often done with the use of style guides.
The Use of Style Guides
A style guide or style manual is a set of standards for designing and writing information for an organization or company.
Style guides are really a quality assurance tool that help define and maintain consistency for an agency’s websites, TBOKS (technical bodies of knowledge), documents and publications.
Style guides establish protocols for details like page layouts, formatting and appropriate company or organization branding. Rules may include what color and fonts can be used and how logos must be displayed.
Kevin Cain, writing for the Content Marketing Institute, states that, "...every company needs a content marketing style guide. Good style guides document and standardize everything, from the unique terminology a company uses to describe itself to its spelling and punctuation preferences." He goes on to say that, " In doing so, the style guide becomes a basic road map that everyone can follow to help create consistent, high-quality business communications."
Read also Cain's article, "6 Steps to Creating Your Content Marketing Style Guide"
When considering the information you are publishing, do not forget the important rules regarding copyright. According to Copyright.gov, "Copyright is a form of protection provided by the laws of the United States (title 17, U. S. Code) to the authors of 'original works of authorship', including literary, dramatic, musical, artistic, and certain other intellectual works. This protection is available to both published and unpublished works."
The source of this definition and more information on registering copyrights, use of copyrights and international copyright laws can be found at:
Copyright protection can relate to the technical writer in two ways:
1. Avoiding plagiarism: Taking care to properly site and/or get permission to use works that that are copyrighted material.
2. Protecting work: Taking care to protect your own work by knowing and enforcing copyright protection laws.
It is important to familiarize yourself with copyright laws and the basics of the topic especially when utilizing the works of other writers.
And while protecting yourself in the area of copyright, peer review can also provide a sense of security. According to Geoff Hart on Techwhirl.com, the goal of peer review is, "...to obtain expert critiques of your writing." Hart says what's important here is to learn to distinguish between valid and invalid criticism, but in the end it should help you be a better writer.
I like that Hart uses the word, "honing". To hone is to sharpen and one of the best ways to sharpen your work is to have a peer writer provide you with a constructive critique. The goal is not to rewrite your work, but to assist you in becoming skilled at writing well through professional suggestion.
Let's face it - there's a risk when your work is reviewed. But, according to a Prismnet.com article, reviewers should be looking for a range of potential problem areas when they review such as:
- Interest level, adaptation to audience
- Persuasiveness, purpose
- Content, organization
- Clarity of discussion
- Coherence, use transition
- Title, introduction, and conclusion.
- Sentence style and clarity
- Handling of graphics
It's not just negative comments that will assist a technical writer when their work is peer reviewed, positive comments also assist in helping the writer know areas where their work is spot on.
Even so, having work reviewed by a colleague or peer is a QA (quality assurance) step that can save embarrassing reports of mistakes later by the reading public.
So you're done with the work and now what? "Documentation control," according to Susan Ward, Small Business: Canada, "is the process of handling documents in such a way that information can be created, shared, organized and stored efficiently and appropriately."
Ward suggests, Steps to Creating a Document Management System which includes:
1. What are the rules for creating documents?
2. How will we store documents?
3. How can retrieving documents be simplified?
4. How can we make/keep our documents secure?
Ward encourages that you can put a document management system in place without costly software or outsourcing. "The system", says Ward, "doesn't have to be complex; you just have to invest some time in planning and implementing it."
Testing and Evaluating the Information
And the final step is evaluation. Successful evaluation and testing of information is important in determining the quality of the work completed. The best test and evaluation comes from the reader/customer utilizing the information so interaction with these individuals is key.
The customer is the best source for confirming that the information is accurate. A select group of users can be useful in becoming a "test bed" for created information. By opening the information up to certain users before it goes public, the technical writer can garner input on a smaller scale and make changes before the information goes out to a greater audience.
Allowing the reader a chance to respond through the use of survey tools is an excellent way to evaluate the usefulness and understandability of materials. From responses given, the writer and/or writers can then "hone" or sharpen the information accordingly.
Technical writing has been around a long time - since man first tried to explain something to his fellow man. Over the past 60 years, with advent of computers, technical writing has grown to include not only print manuals, but on-line documentation and technical bodies of knowledge. Utilizing the pieces of the above pie outlined in this article will ensure that technical writing is done with professionalism and expertise with the main goal of benefiting the reader or user.
Modern Language Association
Amercian National Standard Institute
International Organization for Standardization
Cain, K. (2012, March 5). 6 Steps to Creating Your Content Marketing Style Guide. Content Marketing Institute. Retrieved February 26, 2014, from http://contentmarketinginstitute.com/2012/03/create-your-content-marketing-style-guide/
Copyright Basics. (n.d.). Copyright.gov. Retrieved February 26, 2014, from http://www.copyright.gov/circs/circ01.pdf
Defining Technical Communication. (n.d.). Society for Technical Communication.
Retrieved February 10, 2014, from
Hart, G. (2012, May 21). Peer Review Strategies for Technical Writers. TechWhirl. Retrieved February 26, 2014, from http://techwhirl.com/peer-review-strategies-technical-writers-learning-colleagues/
Online Technical Writing:Strategies for Peer-Reviewing and Team-Writing. (n.d.). Online Technical Writing: Strategies for Peer-Reviewing and Team-Writing. Retrieved February 26, 2014, from http://www.prismnet.com/~hcexres/textbook/team.html
Ward, S. (n.d.). Document Management. About.com Small Business: Canada. Retrieved February 26, 2014, from http://sbinfocanada.about.com/od/management/g/documentmgt.htm