ArtsAutosBooksBusinessEducationEntertainmentFamilyFashionFoodGamesGenderHealthHolidaysHomeHubPagesPersonal FinancePetsPoliticsReligionSportsTechnologyTravel

Quality Assurance for Technical Writers

Updated on February 24, 2017
Source

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:

1. Editing

2. Copyright Basics

3. The Use of Style Guides

4. Peer Review

5. Documentation Control

6. Testing & Evaluating the Information

What to Avoid

  • Jargon

  • Techie Talk

  • Wordiness

Editing

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"

Source

Copyright Basics

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 Basics

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.

Source

Peer Review

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.

Source

Documentation Control

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.

In Review

Source

Conclusion

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.

Other Links

Name
Explanation
Link
MLA
Modern Language Association
http://www.mla.org/
ANSI
Amercian National Standard Institute
http://www.ansi.org/
ISO
International Organization for Standardization
http://www.iso.org/

References

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
http://www.stc.org/about-stc/the-profession-all-about-technical-communication/defining-tc

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


Comments

    0 of 8192 characters used
    Post Comment

    • WVitanyi profile image

      WVitanyi 3 years ago from Edinboro, Pennsylvania

      Nice job! As a programmer who often must bridge the gap between making a program work and explaining what it does, I appreciate your insightful look at this challenging undertaking.

    • carlajbehr profile image
      Author

      Carla J Behr 3 years ago from NW PA

      Thank you, William - much appreciated!

    • teaches12345 profile image

      Dianna Mendez 3 years ago

      What a great post! This is so well done and it is filled with useful information for all writers. Your hub is well designed.

    • carlajbehr profile image
      Author

      Carla J Behr 3 years ago from NW PA

      Thank you, Teaches! This was actually a class project from a few years back that I redesigned. Hopefully, tech writers find it helpful. I appreciate the read.

    Click to Rate This Article