A Toolbox for New Technical Communicators

By Linda Oestreich | Fellow

A Head Start

If you have what it takes, you can make a good living by helping others share ideas and processes through good communication. I’ve been in the business for a long time and I’ve taught countless students about technical writing, technical editing, and information design. To me, all of those disciplines plus many, many more make up what we call technical communication.

But if you’re new to technical communication, you may still be trying to identify what you need to get started.

In this article, I introduce the fundamental skills and tools you need when you enter the field. I’ve divided those things into two basic groups: things you need to have and things you need to know.

Things You Need to Have

In today’s world of the Internet, most critical tools can be accessed online. Style guides, grammar books, dictionaries, and other references that were once available only as hardcopies are now as close as your computer. However, you still need to learn how to use these resources.

Style Guides

You can get the answers to questions from a Google search, but the truth is that the Internet contains a lot of misinformation. So, how do you know when you’ve found the “right” answer to a communication problem? Start by learning to identify legitimate sources. One important source is a style guide.

Style guides can be generic, industry-specific, or in-house. Generic style guides provide a set of standards for writing and can incorporate everything from punctuation to abbreviation choices. They have nothing to do with technical communication specifically, but are authoritative references for language usage.

Industry-specific style guides address things unique to a special field. For example, the ACS Style Guide (produced by the American Chemical Society) contains rules for typesetting chemical formulas.

Finally, in-house style guides are unique to each company, defining their own terminology and usage rules for editorial consistency and clarity.

I am a strong believer that you should buy a good generic style guide and read it. Most of us in this business believe that The Chicago Manual of Style (currently in its 16th edition) is the best of the bunch. It has a wealth of information that you can use as a new technical communicator. (If you want to read a great little book about writing that won’t cost a lot, I suggest you get Strunk and White’s The Elements of Style. It’s not really a style guide, but it’s a valuable read and actually humorous from time to time. It is dated, so don’t take everything in it as true in today’s world. Nonetheless, it is a gem, and I think every good technical communicator should read it.)

If you can’t get a recent edition of Chicago, visit a used bookstore and buy used, older editions. If you don’t have the money, find a generic style guide on the Web and bookmark it (although some of them are only available for a subscription fee).

If you work in the life sciences, you’ll probably use Scientific Style and Format: The CSE Manual for Authors, Editors, and Publishers. People who work in marketing or journalism use the Associated Press Stylebook. Those in the information technology areas or other high-tech industries often follow the Microsoft Manual of Style (MMOS). Other industry-specific style guides abound, and each provides information for a specific area of communication.

Most importantly, when you start a new project, get a copy of the client’s up-to-date style guide and learn it.

Dictionaries and Grammar Books

In addition to style guides, you need a good dictionary and grammar book.

Did you know that not all dictionaries are alike? I once thought that a word was a word and it was always spelled one way, broken into syllables one way, and pronounced one way. Not so. Not only do we have English dictionaries and American English dictionaries, we also have contemporary American English dictionaries, dictionaries of slang, dictionaries of words within a particular discipline, and so on.

The most common dictionaries for American English are Merriam-Webster’s Collegiate Dictionary and American Heritage Dictionary.

If you are working in an area that writes in British English or a language other than English, you need the appropriate dictionary to follow for your work. Find out what the chosen dictionary is and have it handy or bookmark it. If you want a specialized dictionary, you can find one in most any discipline you choose (see this website for a sample: www.yourdictionary.com/diction4.html).

As for grammar books, I seldom use my hardbacks these days. Instead, I look up the problem online. My favorite site is Grammar Girl (www.quickanddirtytips.com/grammar-girl). From time to time, however, it’s good to get the old Harbrace College Handbook off the shelf. Today, the book has a new name: Hodges Harbrace Handbook (www.amazon.com/Hodges-Harbrace-Handbook-18th-Edition/dp/1111346704), and it’s in its 18th printing! Grammar doesn’t change quickly, although some things once disapproved of are now acceptable—despite the kicking and screaming of old purists like me. Because change comes slowly, older grammar books from used bookstores still have value on your shelf.

Content Development Software and Templates

Content development software, also known as desktop publishing or DTP, and the templates within them, are the vehicles you use to produce deliverables—whether online or print. At work, I have always used whatever my client or my employer has provided, and at home I use Microsoft Word because it is prevalent around the planet (if they have a PC).

However, if you are producing documents for single sourcing or content management and can handle embedded graphics, track numbering of tables and figures, create complex tables, maintain cross references, and generate indexes and tables of contents, you probably use something other than Word. For years, Adobe’s FrameMaker was the tool of choice for creating documents in the workplace. Today, FrameMaker has many good competitors, and each has its own strengths and challenges. You can find a good description of different DTP tools in Scriptorium’s Technical Writing 101, chapter 4 (www.scriptorium.com/book/tw101_third_toolbox.pdf). Whatever tool you use, you are responsible for understanding how it works, its strengths, and its weaknesses. Learn how to set up the system and master it, keeping in mind that you might have to start from scratch with each new version of the application!

Along with content development software, you must understand, use, and manipulate templates. Templates are the tool the industry uses to ensure consistency across teams, throughout a project, and within a company. They help ensure that books, documents, websites, blogs, and marketing materials all have the same look and feel. They simplify your work by ensuring that your spacing, headings, margins, typeface, type size, etc., are done exactly the same across time and documents.

Learn about them, use them, and if you’re smart, learn how to build them. Good template developers are rare. (I’m convinced being a template expert provides job security.) For a great treatise on templates, see this blog: http://primacommunications.com/2009/08/the-importance-of-document-templates/.

We could discuss a myriad of other things to supplement your technical communication career. But start by focusing on the three items I’ve noted. Learn them and you’ll be well on your way to success.

Things You Need to Know

Technical communication is a wonderful career because it supports any discipline that uses communication to teach, show, inform, and elucidate. So, what are the things you need to know to launch your career? As an experienced technical communicator, I’ve put a lot of things into my knowledge about bucket, but I’ve trimmed that list to the critical items for new technical communicators:

• language skills
• audience analysis
• information design
• organizational methods
• documentation formats
• global concepts (globalization, localization, and internationalization)

Language Skills

My students often come to technical writing and editing classes thinking that the class teaches them basic English. It does not. Even entry-level technical communication students should already possess good-to-excellent language skills in whatever language they are writing in. These language skills include punctuation, grammar, and style.

Technical writing and editing follow unique rules to help communicate technical information to specific audiences. That unique quality means that, as a technical communicator, you need to change your writing style. For example, alliteration, assonance, flowery phrases, and formal language might be appropriate in higher education classes in the liberal arts, but they have no place in technical writing. Learning about passive voice, misplaced modifiers, noun strings, subject/verb agreement, and comma faults is more important in technical communication than in expository or fiction writing because your ultimate goal is to provide clear, unambiguous information for the reader.

If you are weak in language skills, you cannot be a strong technical communicator. Attend a grammar workshop, take STC classes and workshops at the annual Summit, and do whatever it takes to develop professional-level written communication skills.

Audience Analysis

Every good technical communicator recognizes that communication must be clear in two specific areas: it must have a clear purpose and it must meet the needs of its audience. Establishing the purpose of a piece can be difficult, but you must know why your piece exists to move forward. In the same way, you must know for whom you are writing!

At times, we must address the multiple audiences who all use one document to get answers to their questions. Almost all technical communication addresses one or more of four audience types: administrator, expert, technician, or layperson (Houp and Pearsall):

• An administrator wants to know about time and resources—so you would focus on costs and benefits, the ROI of the work, the training, and resulting revenue of the product you are writing about. They want to know the “bottom line.”
• An expert wants detailed information, including theories and background of the product or research. They want to understand its inner workings from a subjective point of view.
• A technician wants procedures and schematics, information on how to fix or build things, and practical information based on the product’s objective details.
• A layperson wants to know whatever is needed to get the product to do what that person needs. Depending on the product, the layperson might want procedural or explanatory information. They usually need analogies, stories, illustrations, and comparisons with things they already know to help them make sense of the new.

You can learn about your audience through tools such as personas and usability tests. But, no matter how you do it, determining the audiences for your communication and then responding to their needs is critical for your communication to work.

Information Design

Once upon a time, technical communicators worked with graphic artists who helped make decisions about table and art requirements in a document. Today, with PCs and easily obtained graphics and layout programs, anyone can develop graphics. Unfortunately, few technical communicators are an expert in the area of graphics. So, we learn to follow formats and layouts presented to us through templates and best-case examples from experts.

According to Wikipedia, “Information design is the practice of presenting information in a way that fosters efficient and effective understanding of it” (http://en.wikipedia.org/wiki/Information_design).

Your decisions about presentation (design and layout) should be shaped by Robin Williams’s four concepts: contrast, repetition, alignment, and proximity.

You may not be a skilled graphic artist, but it’s paramount that you understand how to select correct color and fonts, correct placement of information, and correct visual elements. Correct design and layout helps users access and understand the information. Good information design can support and enhance ideas—even those that are not well-written. And, poor information design can hinder a message that is written well. Much research has gone into this aspect of technical communication. In fact, you can choose to become expert in information design and/or architecture as you progress in your technical communication career.

Organizational Methods

As technical communicators, we sometimes lose sight of all the detailed skills we possess. One of those areas of expertise that we take for granted is our knowledge of organizational methods.

When you have information to share, how do you organize it? Several solutions exist (from www.kimskorner4teachertalk.com/writing/sixtrait/organization/patterns.html):

• chronological
• cause and effect
• problem to solution
• spatial
• climactic
• reverse climactic
• process
• classification
• compare and contrast

You, as the writer or editor, need to know what method is appropriate for your document. Then you must provide the right keys within your writing so that your reader can follow what you’re doing. When you have no structure and no pattern, your writing becomes convoluted and difficult to understand. To be a better technical communicator, learn to use these and other organizational methods to arrange your content logically and effectively. Remember that organization in technical communication can be different than what you learned in school when writing essays!

Documentation Formats

Technical communicators also must know basic document types and structures. The following list includes some common deliverables:

• memoranda
• user guides
• proposals
• maintenance manuals
• scientific research reports
• travel reports
• feasibility reports
• policies and procedures
• Web pages
• online help
• electronic documents

Over time, you may produce many or all of those products, so learn about as many as you can. You can find information about all of these forms of writing technical communication on the STC Body of Knowledge portal at http://stcbok.editme.com/.

Document structures refer to the internal parts of a document. Each part of a document has a purpose and supports your ability to present a message clearly and concisely. You can find a list of document structures here: www.files.chem.vt.edu/chem-ed/CHP/workshops/samples/structures.html. This site includes information about structures both for online and printed documents, such as headers and footers, tabular material, ordered and unordered lists, headings, pagination, etc. Without these structures, your work would be difficult to interpret.

If you work a lot with online documentation and become involved with the basic makeup of online information design, content management, single-sourcing, and object- or topic-based writing, document structure takes on more and more complex meaning. As you gain experience in the field, you also learn more and more about these aspects of documentation.

Global Concepts

Globalization (G12N), localization (L10N), and internationalization (I18N) have become a major part of any technical communicator’s toolbox in the last 20 years. In the ’70s, a technical communicator usually wrote for an audience from the same country: translation into multiple languages wasn’t a common part of the process and life in technical communication was simpler, if much less interesting.

Today, multiple audiences across multiple countries read much of what we produce. In many cases, technical communicators are on teams with other technical communicators who live, work, and write from the perspective of other countries.

Once again, all you can do as a novice technical communicator is know that these areas of expertise exist and what they are. I recently saw this comment online: “Internationalization and localization are about differentiation. Globalization is about unification.” How true.

Globalization can be a social program, a marketing strategy, a web site, or a software product—G12N is about spreading a thing to several different countries and making it applicable and usable in those countries. When you globalize something, you know it is used around the world and you do all you can to make it workable wherever it is used.

Localization (L10N), rather than making something unified, is the process of adapting the text and applications of a product or service to enable its acceptability for a particular cultural or linguistic market. L10N goes beyond literal translation; in addition to idiomatic language translation, numerous local details such as currency, national regulations and holidays, cultural sensitivities, product or service names, gender roles, and geographic examples must all be considered. A successfully localized service or product is one that seems to have been developed within the local culture.

Internationalization (I18N) is planning and implementing products and services so that they can easily be localized for specific languages and cultures. I18N may include the following tasks in documentation:

• Creating illustrations for documents in which the text can easily be changed to another language and allowing expansion room for this purpose
• Allowing space in user interfaces (for example, hardware labels, help pages, and online menus) for translation into languages that require more space
• Creating print or website graphic images so that their text labels can be translated inexpensively
• Leaving enough space in a brochure to drop in different length languages
• Separating the language elements from the graphic elements, or abstracting content from markup in a web application and software
• Using written examples that have global meaning
• Insuring that the tools and product can support international character sets

As a technical communicator, you are expected to produce documentation that fits these global requirements. Our world is shrinking; as a result, we continually find ways to produce communication that is better received around the globe.

Final Thoughts

It may seem daunting that a technical communicator must know and use so much when starting out. Let’s recap on the main areas presented:

• Things You Must Have: style guides, dictionaries and grammar books, and content development software and templates
• Things You Must Know: language skills, audience analysis, information design, organizational methods, documentation formats and structures, and global concepts

Still, the topics in this article barely scratch the surface of our knowledge. Expert technical communicators collect, analyze, and absorb a multitude of knowledge, and we use that knowledge in varying amounts every day in multiple situations. Soft skills, hard skills, tools, and technology—all belong in the head and on the desk of every good technical communicator.

Keep these basic areas of expertise and equipment close at hand, keep learning about them, and keep sharing your knowledge. You’ll do well.

Linda Oestreich is an STC Fellow and was the 2007–2008 President of STC. She joined STC in 1979 and is a member of the San Diego Chapter and the Technical Editing, International, and Management SIGs. Linda has presented at scores of international, chapter, and regional events. She is currently a contract business analyst for The Marlin Alliance, supporting the director of civilian workforce programs at the San Diego-based Space and Naval Warfare Systems Command. She also teaches the STC online course Technical Editing Fundamentals and two classes at the University of California, San Diego Extension: Basics of Technical Editing and Information Design for Technical Communicators.

References

American Heritage Dictionary of the English Language (5th ed.), Houghton Mifflin Harcourt, 2011.

Associated Press Stylebook (39th ed.), The Associated Press, 2004.

Chicago Manual of Style (16th ed.), University of Chicago Press, 2010.

Document Structures, www.files.chem.vt.edu/chem-ed/CHP/workshops/samples/structures.html.

Glenn, Cheryl, and Loretta Gray. Hodges Harbrace Handbook (18th ed.), Cengage Learning, 2012.

Globalization, Localization, Internationalization and Translation, www.translationdirectory.com/article127.htm and http://philip.pristine.net/glit/en/.

Grammar Girl, www.quickanddirtytips.com/grammar-girl.

Houp, Kenneth, and Thomas Pearsall. Reporting Technical Information (11th ed.), Oxford University Press, 2005.

Industry-specific Dictionaries, www.yourdictionary.com/diction4.html.

Kim’s Korner for Teacher Talk, “Patterns of Organization,” www.kimskorner4teachertalk.com/writing/sixtrait/organization/patterns.html.

Merriam-Webster Dictionary (11th ed.), Merriam-Webster, Inc.

Microsoft Manual of Style (4th ed.), Microsoft Corporation, 2012.

Prima Communications Blog, http://primacommunications.com/2009/08/the-importance-of-document-templates/.

Pringle, Alan S., and Sarah S. O’Keefe. Technical Writing 101 (3rd ed.), Scriptorium Publishing, 2003.

Scientific Style and Format: The CSE Manual for Authors, Editors, and Publishers (7th ed.), Council of Science Editors in cooperation with the Rockefeller University Press, 2006.

Society for Technical Communication’s TC Body of Knowledge, http://stcbok.editme.com/.

Strunk, Jr., William, and E. B. White, The Elements of Style (4th ed.), Longman Press, 1999.

Wikipedia, Information Design, http://en.wikipedia.org/wiki/Information_design.

Williams, Robin. The Non-Designer’s Design Book (3rd ed.), Peachpit Press, 2008.