Category Archives: Reading for a living

Lessons learned in my profession as a technical and biomedical editor

The trainer has left the building: Creating tutorials to leave behind

At a recent meeting of the Chattanooga chapter of the American Society for Training and
Development (ASTD), Derek Bartley of C2Q, Inc. demonstrated how to train a worker to perform a complex task:

  1. Establish a relationship with the worker and find out what the worker already knows about the task.
  2. Provide a context for the task by showing the worker the end product and explaining why it is important to perform the task correctly.
  3. Demonstrate the task multiple times, pointing out key aspects of the task.
  4. Watch the worker perform the task multiple times, discussing key points and any issues the worker may have with the task.
  5. Follow up with instruction as the worker becomes comfortable performing the task
    on the job.

The case for cheat sheets

During this presentation I thought about what happens when the training and coaching sessions conclude. What sorts of print or electronic materials can a trainer leave behind to remind the worker of key points in the task? A training manual may provide everything workers need to know about the task, but readers can get exasperated by the details when all they really want are quick tips and reminders.

I suggest leaving learners with “cheat sheets” – summary work instructions. Cheat sheets can be printed cards, brief files to view on computers or tablets, or brief videos.

If the trainer doesn’t prepare a cheat sheet, workers will. I have seen excerpts from manuals taped to walls in laboratories and pinned to office cubes. I’ve also seen summaries that management painstakingly created and posted on or near equipment. And I’m pretty sure there are YouTube videos for any task imaginable. My quick search yielded, for example, a cheat sheet for quality control in medical device manufacturing, a music industry glossary defining terms used in album manufacturing, an interactive ballistics calculator used to determine ammunition needs, instructions for measuring process work with a time study, and animated fly-tying examples.

To prepare a cheat sheet

Cheat sheets are often tutorial in nature, emphasizing the key points that are described in full during training sessions. To create an effective print or electronic tutorial:

1. Start simple

These are the five elements of a simple procedure:

  • A title
  • A conceptual element (Why perform the task?)
  • An infinitive subheading (Example: “To calibrate instrument optics:”)
  • Steps in the procedure (Limit the number of steps in a procedure to 10 to 12 steps; break a complex procedure into a series of independent, manageable tasks.)
  • Notes

You can number steps, put them in a table, or even show the steps graphically and skip most of the words. The goal is to provide an at-a-glance reminder of how to perform a task.

2. Eliminate elements

  • Combine the title with the infinitive subheading. (Example: Title a summary of tying a particular type of fishing fly “To tie a shad fly:”)
  • Eliminate conceptual material; cross-reference or link to complete explanations of why the job is important or to theory of operation.
  • Pare down or eliminate notes, again by cross-referencing to complete documentation.

Note: Be careful not to eliminate required safety notes or conceptual material crucial to safe operation of equipment.

3. Cut away the details

Get rid of repetition by placing tasks repeated over and over again in one spot. For example, if an electronic task requires multiple login steps, explain how to log in once, up front. Then refer to these instructions at the appropriate point in the procedure. (Example: “Log in a second time as an Administrator to access security settings.”)

Combine multiple related actions into one step. (Example: “Ensure that you can reach all controls, adjust the seat and mirrors, then start the forklift using the key and the start button, as shown.”)

Delete intuitive procedures that require little explanation. For example, if installing a software upgrade is straightforward and the user interface easy to follow, tell users how to start the installation and then direct them to follow on-screen instructions.

When to focus on concepts, not steps

In some cases, concepts are more useful than step-by-step instructions. Sometimes a process or product is so well designed that reminders are not necessary; you can focus on concepts and minimize procedures. Experienced workers may want to know what else they can do with a product, or how to streamline a process for increased efficiency. Scenarios based on common usage help give the learner context for the task at hand. Parts lists might be helpful if workers need to replenish or replace parts frequently. For software, if new users are likely to have problems navigating through an interface, an interface map or flowchart may be more useful than a detailed set of steps.

Were rules for hyphenating compound modifiers made to be broken?

I don’t spend a lot of time thinking about punctuation, but when I’m proofreading I consider every punctuation mark. Today I’m thinking about hyphens used with compound modifiers – and how following strict hyphenation rules can easily distract the reader.

Actually, there are few hard-and-fast rules about hyphenating compound modifiers. As a general rule, hyphenate a compound modifier that comes before a noun (full-time employees). But even then, you can use your own judgment.

 (Almost) always hyphenate

Hyphenate these compound modifiers when they come before a noun:

  • Color terms when the elements are of equal importance (blue-green dress)
  • A cardinal number and a unit of measurement before a noun (100-yard dash)
  • Adjectival compounds beginning with high and low (high-level programming language)
  • Adverb-adjective combinations (much-loved character)
  • “Two-thought” compounds (socio-economic)

Hyphenate compounds beginning with self or half, whether or not they precede a noun:
I believed he was self-reliant. This idea turned out to be half-baked!

(Almost) never hyphenate

  • Combinations that are ordinarily hyphenated before a noun are often not hyphenated
    after a noun: Employees who expressed satisfaction generally work full time.
  • Don’t hyphenate adverbs ending in ly + a participle or adjective (a highly complex system).
  • Word-forming prefixes do not require hyphens: anteroom, binomial, infrastructure.
  • Proper nouns (anti-Semitic)
  • Words that without hyphens could look like other words (un-ionized)
  • Words with identical letters that need separating (pre-empt)

Exceptions to the almost-never-hyphenate rule:

Breaking the rules

All these rules are helpful, but style guides almost always admonish readers to seek clarity before slavishly following rules. Applied without restraint, hyphenation rules can result in a sea of hyphens that make the text difficult to read. If sentences are succinct and clear, I suggest not over worrying about hyphenation.

Lessons learned as a freelancer in 2013

After a whirlwind end-of-year editing extravaganza, I now have some time to consider what I learned as a freelancer in 2013. Here’s what I know now that I didn’t know (or couldn’t face) a year ago:

Clients don’t necessarily need you when you need them.

In 2013 a new client did not materialize until midyear. I spent the first part of the year
worrying about how to survive and wondering if I’d make it as a freelancer. I spent the last half of the year worrying about how to do holiday shopping when I had to work days, nights, and weekends.

The big lesson, of course, is to budget: Save money so you can live during downtime (easier said than done when your 12-year-old car falls apart and your roof springs a massive leak).

And budget your actual time as if you were working. Early last year I began filling my time
with Meaningful Activities. I volunteered, and I flung myself into personal and professional
development: I joined a garden club, started a blog, joined a second professional organization, developed a brochure, and exhibited in the “Consultants Corner” at a convention. When paying work came up last summer, I found myself with several non-paying commitments that I no longer had time for. I had to go for the money.

Build time for your life into the schedule.

Sometimes personal obligations come before professional ones. In 2013 my mother went to a nursing facility and my dad to assisted living. I spent time driving my dad to see my mom,
discussing medical decisions with doctors, and helping both parents adjust to living apart after 62 years of marriage. Occasionally I had to tell clients and professional associates that I was behind and why. They all understood. Clients can be difficult and demanding, but they can also be compassionate and empathetic when you have to make room for family in the work schedule.

Promise only what you can deliver.

My friend Steve Wilson, a business consultant and manager, sent me a time management
plan with tips that seemed at first a little outlandish. The tip that caught me off guard involved setting a maximum workload and being honest about it with potential clients. Steve told me to look at my current workload and the maximum number of hours available to work, then determine a delivery date to communicate to a prospective client. I’d risk losing the client by being up front about that date, but I would not lose my reputation for honesty. And producing a deliverable on time or early would only enhance that reputation.

Communicate with clients before going over budget.

I’m still learning about estimates. Until I start working, I rarely know the extent of writing and editing required. If the material is complex and content is scarce, the job can take can take a lot longer than expected. If possible, I clarify that the original estimate is just that – an estimate. Then I communicate regularly with the client about progress made toward reaching project goals. If I see that a task is headed toward being over budget, I talk with clients about their
preferences. Would they like me to return a draft? Complete the job at greater expense? I have discovered that clients are often more concerned about a job well done than about manageable cost overruns.

Clarify technical details up front.

I took a job that required use of a technical publishing system. The current version of the publishing system was available only on PC and I had a Mac, so I bought a PC and the publishing system. I happily did the work and I really appreciated the opportunity to learn the ins and outs of the publishing system. When I turned files over to the production staff, I learned that the client had an early version of the publishing system and the production staff could not open my files! Eventually we figured out a way to create readable files for the client, but it was painful.

In retrospect, the issues could have been avoided if I had gotten version information about the software required. I probably would not have purchased an antique version of the publishing system, but I might have worked out a way to use client equipment and software, or I might have talked to an IT professional to resolve compatibility issues up front.

You can fail a test long after you’re out of school.

Sometimes I’m invited to take an editing test, usually by an organization providing editorial services to technical and medical professionals. Some organizations pay editors to take tests. I’m always amenable to taking a test, paid or not. After all, I got my first technical writing job after taking a test!

The tests I took this year had time limits, and I didn’t meet them. I carefully looked up a lot
of medical terms that I don’t use every day, and I was methodical in my edits. But I honestly reported my time, and I didn’t get any work as a result of the tests. Recently I experimented with one test and did a less-than-stellar job within the allotted about of time given. We’ll see what the employer thought about my “good enough” attitude. I suspect not much.

You never know where your next job will come from.

Here I am at the beginning of 2014, with time on my hands to blog, edit my LinkedIn profile, revisit my resume, and search for new jobs. In 2013 I got jobs through professional organizations, former employers and coworkers, and friends at church and on the tennis court. It turns out that all my downtime at the beginning of 2013 gave me a chance to be social and network my way into the next job. Here’s hoping networking pays off again in 2014!

Handling numbers in your documents

I have been reading marketing literature for one client and scientific procedures for another client. I notice differences in style, and I’m particularly interested in the special problems posed for writers of each type of literature when it comes to handling numbers. Scientific writers puzzle over long numbers and line breaks, whether to use a comma or a period to signify a decimal, and spacing between a numeral and a unit of measure. Marketers have to decide whether or not to follow the Associated Press rules regarding spelling out single-digit numbers when numerals can call attention to product advantages. All types of writers seem to have trouble knowing when to use a number and when to use a bullet in a list. Here are a few tips on presenting numbers in your documents:

When to spell out numbers and when to use numerals

The general rule: Use words for numbers zero through nine and use numerals for numbers starting with 10. (The Chicago Manual of Style advocates spelling out numbers zero through 99.) It is acceptable to use all words or all numerals when presenting numbers in a series (Example: 1, 99, and 200)

Scientific publications often use numerals rather than words to represent single-digit numbers. The Council of Science Editors, for example, advocates the consistent use of numerals in text: “This style allows all quantities to be expressed in a similar manner, and because numerals have greater visual distinctiveness than words, it increases the profile of quantities in running text.” To avoid confusion, however, the Council recommends spelling out zero and one.

Scientific publications often use numerals rather than words to represent single-digit numbers. The Council of Science Editors, for example, advocates the consistent use of numerals in text: “This style allows all quantities to be expressed in a similar manner, and because numerals have greater visual distinctiveness than words, it increases the profile of quantities in running text.” To avoid confusion, however, the Council recommends spelling out zero and one.

Other rules:

  • Use words for numbers that begin a sentence, unless the sentence begins with a calendar year or an organization or product name that begins with a number.
  • When two numbers are next to each other, spell one of them (Example: 28 twelve-foot boards).
  • Use words in quotes and dialog.
  • Use words for simple fractions (Example: one-half).
  • Use numerals with other fractions, except at the beginning of a sentence.
  • Use numerals to show the age of a person.

Using numbers in lists

Bullets are ubiquitous in presentation materials, probably because bulleted items are built into presentation software. Lists are great ways to present material that audiences scan. They are great for visually organizing training and technical material for easy comprehension. But be sure that you use the appropriate type of list to present the material.

When should you use numbers in a list? When you need to to show order:

  • To describe procedures and processes. Most how-to-do-it or how-it-works text benefits when you number steps that must be performed in a certain order.
  • To show order of importance.

Use bullets when order is not important or when all items have the same weight.

A note about lists

Bullets and numbers signify that you are presenting lists, and a list contains more than one item. Even in presentations, I avoid using a bullet with a single item.

AP style revisited

In my last post, I said I preferred the Chicago Manual of Style to the Associated Press Stylebook and Briefing on Media Law 2013. The Chicago manual contains lots of detailed examples from different disciplines, and it is well indexed. The AP stylebook seems thin on specific examples, and finding material in the print version is difficult. But just when I thought my preferences were set in concrete, along came a supplemental handbook that cracked my resolve.

Working with Words: A Handbook for Media Writers and Editors by University of Missouri journalism professors Brian S. Brooks, James L. Pinson, and Jean Gaddy Wilson provides plenty of
detailed information on grammar, sentence structure, and journalistic style. The handbook is designed to help journalism students create engaging print, radio, television, and online
communications, but it is useful for anyone who wants to connect with readers, viewers,
or listeners.

AP style expanded and explained

The authors wrote the book because there was “no single, comprehensive resource a member of the working press could turn to” to answer questions about grammar, usage, punctuation, spelling, and common writing practices. They wrote this text to elaborate on the AP stylebook. The handbook is divided into several topics:

  • Grammar and usage
  • Punctuation and spelling
  • Style
  • Writing methods for different media

It also includes an appendix with summaries of material in the first four parts of the book,
bibliographies, and a very useful index. The inside back cover lists 20 common errors in news stories, with page references to the authors’ discussions of those errors.

What I like about this book

I prefer reading fiction to reading style guides (call me crazy), but this handbook is actually fun to read. I’m not a journalist, even though I know something about “inverted pyramid” style and the need to write simply and clearly. I am, however, an avid reader of the newspaper and,
perhaps to my discredit, a big consumer of television and online news. So I read the detailed formulae and examples on writing for different media with interest, sometimes nodding my head when I recognized a method of presenting material that seemed familiar.

I like the outside-the-box ideas for changing the rules when necessary. Reversing the traditional order of a news story, for example, can startle the reader to attention. And I like the what-not-to-do lists, which are quite lengthy. I have to admit recognizing clichés that I have used over the years – starting an article with a question, a dictionary definition, a “you might think/think again” lead (and that’s the short list). Thankfully I have never written anything that began “Yes Virginia, there is a Santa Claus.”

Finally, I find the chapters on non-print media very interesting. I have written for radio (and it was difficult), but I always wondered how one structures a television story. In the online media chapters the authors discuss what does and does not transfer from print, how to vet online sources to ensure correctness, how to layer and chunk online stories for readers who generally scan, how to edit your own copy, and how to write for social media – including blogs! I suspect that the authors will have more to say on social media and online communications, with their special ethical issues, in future editions of this book.

Divided loyalties

So now, even though I continue to be loyal to the weighty Chicago Manual of Style when it comes to technical writing, I’m beginning to think that AP style is a little more fun to use
when you aren’t bound by the conventions of specialized technical communication. And I
recommend Working with Words to anyone who wants to communicate information in a clear,
compelling way.

Note: The academic press Bedford St. Martin’s (bedfordstmartins.com) publishes Working with Words and associated print and online exercises. 

A matter of style

I recently began an editing job in a marketing communications department. The department has style standards, but when questions arise, writers use the Associated Press Stylebook and Briefing on Media Law 2013. During my time as a technical communicator, the The Chicago
Manual of Style
was my go-to style source. So I decided to do a little comparison of the AP stylebook and the Chicago manual to see which one I’d prefer to take with me if, say, I had to choose one style guide as my only reading material before running for cover during a zombie attack.

Granted, the audience for each book is different. I did a search and found a lot of discussion of actual writing rules (I’m with the University of Chicago on the serial comma by the way). The differences seem not so significant; both books demand clarity and consistency in writing no matter who the audience might be. But to me there seem to be differences in the authors’
approaches to preparing a style guide. I wanted to focus on the accessibility of information in the books.

The Associated Press Stylebook is so 21st century.

The AP stylebook is definitely an easy read. I used this guide 30 years ago when I worked briefly in public relations; then it was called a style guide and libel manual. Now, things are more complicated, and so is the guide. It still focuses usage, containing definitions and correct spelling for words from Amber Alert to website. And it still provides a guide to punctuation. But in place of the libel manual there are appendixes on news values and media law, including guidelines for social media, sports, food, fashion, and business; a guide to writing stories for broadcast; and a guide to using interactive graphics in news stories.

I like the casual nature of discourse and the “everyman” approach used in the AP guide. In a world of mass electronic communication and social media (including participatory wikis), all writing – including technical documentation – is casual in tone and style.

I find the AP guide simple and easy to use. The usage section consists of an alphabetical list of terms, so it is very easy to find without an index. And that’s a good thing, because I couldn’t find an index in the AP guide. The best way to navigate this guide might be online using the search function.

Get all the specifics in the Chicago Manual of Style.

The Chicago manual is detailed, with many examples from many different academic disciplines. I can usually spot an example related to the topic of the text I am editing, no matter how
obscure that topic may be. The index is exceptionally detailed, so I can find just about any information I’m looking for. But index use is hindered, in my opinion, by the military numbering system used for headings in the Chicago manual. The numbering system and references to numbered headings in the index make finding information pretty frustrating. Pre-electronic everything, technical communicators annotated their print copies of this guide to find often-looked-up topics easily. I have heard of senior editors handing down their treasured annotated copies of this manual to their favorite junior editors upon retirement!

I was mulling over the index issue when it occurred to me that indexes seem to be on the road to extinction, perhaps because you can always buy a searchable version of any book. In fact, you can get an online subscription to most style guides. Electronic subscriptions are useful
because style is not static, and it becomes tiresome and expensive to buy new versions of these sometimes-bulky documents every time they are revised to reflect changes in language and culture.

I can’t resist playing it safe.

Despite its drawbacks I’d probably choose the academic Chicago Manual of Style over the hip AP guidebook. Why? The Chicago manual covers many different disciplines, it is detailed, and it is well indexed. Most importantly, or maybe most foolishly, I like it because I’m accustomed to it.

I recently bought an online subscription to the Chicago manual. But I couldn’t resist buying
another print copy too so I’d have the latest and greatest edition on hand in case of zombie
attack and subsequent loss of Internet connection. Better safe than sorry.

Technical communication and Millennial madness

The Millennial generation born to baby boomers in the 80s and 90s came of age in the 2000s. This swell in the population now represents a big portion of the labor pool; by 2020 Millennials will make up 46% of the work force. Because of their size and their distinctive buying, learning, and work habits, this generation is the subject of much discussion among marketers, educators, and personnel managers. Recently I did a little thinking about how to communicate with Millennials about technical topics.

Characteristics of Millennials

Self-confident. Some writers criticize Millennials as over confident, with a sense of entitlement instilled by “helicopter parents” who encouraged them to feel good about themselves even when praise was not earned. But there is merit in confidently approaching a task (or a document, a help system, or a user interface) with the assumption that you have the wherewithal to accomplish it.

Wired. Millennials are “digital natives,” and they’re savvy with social media. They use smart phones. They are expert gamers.

Social. According to Susan M. Heathfield in an About.com article, “Millennials are the most connected generation in history and will network right out of their current workplace if these needs are not met.” They like working on teams. They make an effort to seek peer approval before making decisions. They like to talk. They are socially conscious and civic minded.

Lifelong learners. Millennials expect to learn new things as part of their everyday work and personal interaction. Recently I asked a Millennial what he didn’t like about his job. He hesitated a moment, then said sadly “I’m not learning anything.” For Millennials, even ads need to teach something.

Scanners. Millennials are “scanners” who can take in a lot of visual information at once – they believe themselves to be true multitaskers.

Value work/life balance. They don’t want to spend all their time struggling over their work.

Penny pinchers. Most surprising to me, Millennials are frugal. Their salaries are typically lower than those of their predecessors. To purchase high-ticket items (like electronics) and more education, they scrimp and save. Wired and big on learning, they have perfected the art of comparison-shopping. They join car-sharing organizations to avoiding buying cars. They’re socially conscious so they demand green products and packaging.

How to engage Millennials

Common advice to those who manage, teach, and sell to Millennials:

  • Provide structure
  • Emphasize teamwork
  • Use their electronic literacy
  • Change assignments or give them multiple assignments
  • Make the workplace, learning experience, or ad campaign fun

How to communicate technical info to Millennials

Gamify. A leading proponent for gamification in technical communication is Oracle’s Marta Rauch. Rauch says that gamification “uses game techniques in non-game situations to motivate people and drive behavior.” Technical communicators can manage user interfaces and assistance for gamified products. And we can gamify our own communication products by providing goals, rules, feedback, and rewards.

I attended a session on winners in the International STC publications competition, and one winning entry was a training video for a fast-food restaurant. Trainees play a fun game, receive rewards and positive feedback, and generally learn how to do their jobs in a way that would be fun for anyone, no matter what generation you happen to be born into.

Note: Follow Marta Rauch to learn more about gamification and other cool things at
martarauch.wordpress.com.

Emphasize structure: Helicopter parenting created a generation of people accustomed to structure in their lives. Establish the purpose, learning goals, and structure of your documentation product and then test users to be sure that they have met expectations.

Make your documentation accessible at a glance: If you’re using “slow” media, remember the way Millennials read. They scan, taking in lots of visual information at once.

  • Make online information uncluttered and easy to view
  • Properly index print documents
  • Tag and bookmark online documents
  • Provide logical navigation tools in help systems
  • Label text, tables, and graphics with meaningful headings and captions

Listen to your users. Millennials are accustomed to talking and being listened to. Mine wikis, message boards, and social media sites for information. Seek feedback through social media and focus groups to take advantage of Millennials’ social nature.

Spruce up your writing style. Be direct, pointed, spare, and casual. Ideal strings of text in a gamified product, says Rauch, “are the length of a tweet.”

What’s good for Millennials is good for everyone

These are just a few ideas for effective communication to Millennials, and they work well for everyone. What trainee would prefer dry pre- and post-tests to a fun game? Who among us has not given up on the manual and turned to the message boards for answers to what seems like easy questions? Heck, I often skim the novels I read for fun, especially when the writing is verbose; I’m unlikely to read every word of a technical manual. And whether you are a Baby Boomer or a baby, you’re probably acquainted with electronic communication. Even my
Greatest Generation dad reads books on his trusty iPad.

The joy of outlining

Whether you’re writing a white paper, a set of instructions, help for a mobile app, or a simple blog post, your first step is planning. And planning means analyzing your audience, defining a purpose, gathering information, and developing a preliminary outline.

Why create an outline

Why bother with an outline when you have all the information you need tucked safely away in your head? An outline ensures that some of that extensive information in your head isn’t inadvertently left there, never to make its way onto the page or screen. It helps you keep on point, so that you don’t distract readers with nonessential information. It helps you stay on task despite disruptions and distractions.

An outline is a map you can use as you to develop, revise, and test your ideas with reviewers. It can make the writing experience straightforward. And if you take pleasure in efficiency, an outline can help make the writing experience downright fun.

Choose your outline type

To prepare a detailed outline, sort the information you have gathered into topics of relatively equal importance, then identify subtopics. For short documents like quick references or online help topics, you might choose an informal outline, which can be a simple numbered list of topics. For example, if your task is to write a quick reference card on preparing for a laboratory procedure, you might use the following informal outline:

1. Draw blood.

2. Store blood.

3. Dilute samples.

4. Purify samples.

5. Clean prep station.

For more complex documents, choose a formal topic or sentence outline. A topic outline uses key words, and it includes subtopics. A sentence outline develops topics using complete sentences. For most documents, a topic outline provides an adequate guide. But if you are writing a lengthy document – say a chapter or section in a book – consider writing a sentence outline that provides specific details.

Example topic outline on outlining

I.    Why an outline is important

A. Provides a map to follow as you write

B. Makes sure relevant information not dropped

C. Keeps extraneous information out

II.    Types of outlines

A. Informal numbered

B. Topic

C. Sentence

D. When to use each type

III.   Drafting a document using an outline

Note: Headings and subheadings stand for divisions of information, and a division means that there are at least two parts. So, a single subhead – “A” for example – cannot exist without a second subhead, “B.”

Draft the document

Expect to change the document’s structure as you write, even if you’re using a detailed outline. What looked simple in the outline may be convoluted in the first draft, so you create some new topics as you’re writing. Or, what you planned as a major section may contain very little information, so you opt to subordinate that information in another section.

The outline is a guideline, not a rule, and you’re allowed to change your mind as you write. In my example topic outline on outlining, the final subtopic under “Types of outline” is “When to use each type.” But when I wrote the blog post, I found it easier to incorporate a discussion of when to use each type of outline when I defined the type. Also, I thought of a new topic on how to use an outline when you are preparing a revision for publication, so I added it as a tip at the end of the post.

Evaluate document structure

After you have completed a good draft, reevaluate the document’s structure. Is the flow of ideas logical? Is the text coherent and complete? If you have a table of contents, you have a quick way to evaluate overall logic before you revise and edit what you have written. Any initial headings you have used in the document provide another sort of map to your document’s structure. You’re looking at general structure, not specific text. Reorganize any parts of the text necessary before you refine the document in the next draft.

A tip on revisions

If you’re writing product documentation, you probably have to update print and online documents to accommodate product updates. Sometimes there is a need to restructure before you add new content. Try outlining the original to see if you can find logical flaws, and revise the outline to correct the flaws. Then, reorganize the old text and add new content using your new outline. Using an outline to correct flaws in the original can be a source of joy not only to the writer but also to the reader who no longer has to endure a difficult-to-follow document.

Gender-neutral Technical Writing | TechWhirl

At the recent STC Summit in Atlanta, I noticed that keynote speaker David Pogue used she as a singular pronoun rather than he, he or she, they, or some gender-neutral combination of he and she. I thought his usage interesting and not offensive. However, as an editor I have recently had to rewrite awkward attempts at gender-neutral writing, and I thought gender-neutral language in technical communication would be a good blog topic. Right off the bat I found an excellent discussion of this topic and it says everything I can think of to say on this subject, plus some. This article, “Gender-neutral Technical Writing,” was written for TechWhirl by Jen Hollis Weber.

Gender-neutral Technical Writing | TechWhirl.

“Mistakes were made”: Passing on passive voice

Your high-school English teacher forbade the passive voice verb construction in favor of spare, lively active voice. But your university science professor insisted on objective, impersonal passive voice. Now you’re writing about science. When should you use passive voice?

Most editors recommend against passive voice unless you want to emphasize results, describe a natural or mechanical process, or create a transition.

What is voice?

In active voice, the subject performs the action. For example: “The software generates a ranked list of possible peptides and proteins for each spot.”  The subject, software, performs the action.

In passive voice, the subject receives the action. The grammatical construction for passive voice involves a form of the verb “to be” together with the past participle of a verb. For example: “A list of possible peptides and proteins for each spot is generated by the software.” The subject, list, receives the action, is generated. The actor in the sentence is the object of the preposition by.

Why is passive voice a problem?

Passive voice in scientific and technical writing is often considered dignified; lively writing seems, well, undignified. In a 1996 letter to the editor of Nature, chemistry professor Leon Avery says that “liveliness of style is the worst sin” in the scientific writing. Try telling a joke in a scientific paper, he suggests, and see what happens.

But lively writing is not your goal as a communicator; clear and concise writing is. And that’s the best reason for choosing active voice. Passive voice often results in unclear modifiers, unnecessary words, and ambiguity as to the agent of the action. The writer may view passive voice as dignified, but the reader often perceives it as a source of confusion.

When should you use active voice?

Use active voice when you need to be direct, clear, and concise. Use active voice for instructions, for example. In fact, use active voice most of the time.

Look again at our example from a biotech software guide: “The software generates a ranked list of possible peptides and proteins for each spot.” In this example, it’s important to know who or what generates the list, the user or the software. If you want to emphasize the actor in a sentence, use active voice.

When should you use passive voice?

Some writers use passive voice to describe a natural or mechanical process if the actor is irrelevant or unknown. (I’m including software processes in the definition of a mechanical process.) Use passive voice to emphasize the recipient of the action. And, use it for emphasis or to show transition from one topic to another.

Take, for example, the following figure caption: “Real-time PCR data with insufficient input gDNA. gDNA was added at concentrations ranging from 0.01 to 20 ng per reaction. At 40 cycles, many of the PCR reactions have not reached the plateau stage of PCR.” In this caption, who did the adding is not significant; gDNA is. Repeating gDNA at the beginning of the sentence after the caption phrase provides a transition to the explanation of why the input of gDNA was insufficient.

Passive voice can effectively emphasize results. When you deliberately choose passive voice, be sure to maintain parallelism; don’t start a sentence in active voice and then shift to passive. Avoid passive constructions that result in awkward or misplaced modifiers.

One final word of caution: Don’t recast an effective passive construction just because your English teacher (or your editor) told you to. This quote from Thomas Edison breaks all the rules, but it works:

Opportunity is missed by most people because it is dressed in overalls and looks like work.