Category Archives: A question of style

My response to questions about style in technical communication

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.

Choosing words carefully

Business writers take pride in writing clear, concise, grammatically correct communications. But sometimes even the most precise communicators have difficulty knowing exactly the right word to choose:

Dear Style Master: One of my coworkers insists on using “percent of employees” in
business communications about management. I think she should be referring to a
“percentage of employees”. Who is correct?

– Fractious

 Dear Fractious: I see these two terms used interchangeably, but somehow “percent of a
number” doesn’t sound right to me. After a little search I learned that percent should always be accompanied by a number; percentage is used when no number is present. So, you might say that 98 percent of company employees reported satisfaction with the new time-reporting
software, and only a small percentage of employees had difficulty using the application. Fractious, I think you are correct!

The answer to your question is, in my opinion, unambiguous. But read on for a couple of word-choice questions that don’t have such definite answers:

Dear Style Master: When do I use “less” and when do I use “fewer” with percentages? I know to use “fewer” with countable nouns and “less” with nouns you can’t count, but are percentages considered countable or mass nouns?

Less Than Certain

 Dear Uncertain: To me, you are referring to a number of countable things when you speak of percentages. For example, you might say that fewer than ten percent of employees have difficulty using the new time keeping system. The noun employees is countable.

The trouble is that different style guides give us different direction. The experts at Chicago
Manual Online say that less is ok with percentages, because tradition holds that you use less when referring to time, amount, or distance. Percentages are amounts. But the AP stylebook agrees with me that, since you can count employees, fewer is correct.

If you look at online forums on style, you’ll see a lot of argument on this subject. So the answer is less. Or fewer. Either way, you’re certain to be correct.

Dear Style Master: Prior to encountering my current editor, I used “prior to” all the time in my project documents. But now, my editor is suggesting that I use “before” instead. Why?

Professional Documentation Project Manager (PDPM)

Dear Pro: Some editors say that prior to is grammatically incorrect because prior is an adjective (I couldn’t come to the party last night because I had a prior commitment). Others think prior to is just an affected, bureaucratic phrase that means before.  However, dictionaries generally
accept prior to as an informal noun phrase. So, prior to doesn’t seem to be flat out incorrect. It’s just annoying. I suggest using before to mean before and prior as an adjective, even if you’re a bureaucrat. (I’d also use after instead of subsequent to.)

Rules for numerals

Dear Style Master: Why do I have to spell out numbers at the beginning of sentences?
Numerals Rule!

Dear Ruler: Honestly, I don’t know why. I have searched high and low for the reason that the rule in all style guides is to use words rather than numerals to start sentences. My guess is that this rule has something to do with readability.

As with any rule, however, there are exceptions. Some style guides say you can begin a
sentence with a calendar year (“2013 was a tumultuous year for our family”) or with the name of an organization that begins with a number (3M). Headlines in news and marketing copy
also tend to use numerals rather than words to represent numbers. Using numerals at the
beginning of a sentence for emphasis, especially if they are treated graphically, makes sense to me. For example:

97% of our customers give us positive ratings for customer service!

In fact, a lot of marketing documents use numerals all the time, because they stand out and make readers take note.


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 ( 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.

Simplifying online help

Dear Style Master: How can I reorganize my thousand-topic online help system supporting a business software application? Customers are having trouble navigating the system to find out how to use the software to do their jobs!

– Everything but the Kitchen Sink

Dear Sink: It’s great that you know what customers think about your system. Often we labor over product documentation, release it, and never know the value of our work to customers. As far as reorganizing, I suggest taking a cue from Thoreau: Simplify, simplify, simplify.

Start by creating workflow diagrams for each task customers will perform. In each diagram, list topics in the order in which you would use them to accomplish a task. Be sure that every topic in the system is listed in at least one workflow diagram. Hint: If a topic doesn’t fit into one of the workflow diagrams, maybe you can delete it from the system.

Next, look at the diagrams and see if there are topics you can eliminate, being careful not to eliminate a topic critical to multiple tasks. For example, identify background, reference, and detailed instructional material that you can move to another document, like a user guide. You can always link to the user guide from the help system so that the reader can find additional information easily. You might also be able to delete unnecessary graphics and confusing cross-references. If you are in doubt about cutting specific topics, ask an editor, reviewer, or peer to weigh in on whether or not to remove the items from the system.

Finally, review the existing system topic by topic. Edit wordy text and eliminate the obvious – phrases like “Respond to the ‘Are you sure?’ prompt” may not really be necessary.

After you revise and release your help system, continue your quest to know how customers view your system, through usability testing, standard customer feedback tools, or maybe a friendly phone call.

Quick tips on verbs

Dear Style Master: I’m troubled by verbs. In addition to changing passive verbs into active verbs, my editor changes future tense to present tense in all my instructive content! She also says I tend to nominalize. What the heck is she talking about and how can I stop these irritating edits? 

–Futuristic UX Expert

Dear U: Help your editor (and your user) out by sticking with present tense most of the time. Many of us tend to use future tense as a kind of prediction of the consequences of an action: “When you press Return, the Review window will open.” The truth is that when the user presses Return, the Review window opens.

Avoid nominalizations that result when you take a perfectly good verb and make it into a weak, abstract noun. Like passive voice, nominalizations can result in some awkward constructions. For example, rather than simply suggesting that a user calibrate an instrument, you might nominalize to suggest that the user perform a calibration—and your editor will take you to task!

Unsettling your readers

Dear Style Master: What is an “unsettler”?

– Ruffled writer

Let’s face it, Ruffled: Even though they support very exciting technologies, technical manuals are rarely as absorbing as a good mystery or even the morning newspaper. It’s pretty easy to overlook a critical step in a protocol or a crucial requirement in a software installation guide. As the word implies, unsettlers prod readers into paying attention when they should. You might begin a paragraph with “IMPORTANT!” to call attention to a cautionary note. Other unsettlers are questions posed to the reader, hyperlinks to critical information, checklists, tables, and graphics. Used infrequently, unsettles catch the reader’s attention. (Used with frequency, unsettles lose some of their power.)