Category Archives: Instructions

Fix This Writing! Jed’s Customer Email

The terrific Leslie O’Flahavan, owner of E-WRITE, and I recently held our first LinkedIn Live broadcast of Fix This Writing! Two Experts Show How to Make Bad Writing Better. Watch the recording and view the writing we discussed below.

The idea behind our broadcast is to take an example of not-very-good writing, explain why it’s not good, and show you how to fix it. We also talk about why the writer wrote it in that not-very-good way. (We’re both writing teachers, so we’ve studied why people write they way they do!) We invite our attendees to ask questions, as well as to offer their insights.

For the first broadcast, we examined the following customer support email that failed.

Our discussion began by recognizing that Jed, the writer, is probably working within a company that doesn’t support his writing skills much–or customer service in general. But we moved quickly into our primary purpose: to help Jed write a better message.

While acknowledging there are many aspects of the original email that could be fixed, I focused on what I believe are the two most important ones.

Fix #1: Make your tone helpful and friendly.

What comes first establishes the tone. I personally don’t want to be thanked when asking for help. For me, that created a negative tone in the original email. But Leslie and others more knowledgable about customer support noted this is the standard opening so I acquiesced.

I did insist that the most important fix I needed at the outset was reassurance that I would get help. In the revised email, I added “we want to help” to create a more helpful and friendly tone in the first sentence. You’ll see that I also used the contraction “we’re.” That’s another way to establish a friendly tone. Of course, casual tone of voice might not work in every organization. That’s depends on the organization’s brand voice.

Fix #2: Structure information in reader-friendly ways.

This fix is so important I might have listed it as #1! Jed’s original email included most of the information a reader needs. But it’s arranged more from his perspective than the reader’s. What the reader needs are instructions that are actionable. Here are some of the ways I altered the structure to be more reader-friendly.

  • Arrange information in the order that the reader needs it when acting on it. The information I labeled “OPTIONAL STEP” is frustrating (or perhaps useless) if the reader gets it after they’ve acted on the instructions. In the revised email, I moved that prerequisite information before the primary instructions.
  • Make action steps short and number them in a list. I revised Jed’s long sentence with three independent clauses into three, consecutively numbered action steps within a list.
  • Differentiate action steps from other information. In the revised email, I used capital letters as a visual cue to all steps. I also used white space to group steps that go together.

Other fixes…

You’ll notice other fixes in the revised email. For example, the arrow shows I want to include a photo to show the reader where to find the SD card. In instructions, visual support can be critical for readers.

You’ll also see I fixed the grammar of phrasing such as “does the dash cam cannot turn on” and “…the cam stop working issue.” While it was one of the first things I noticed when reading Jed’s email, I believe the majority of customers asking for help care most about (1) getting that help, especially from someone who is friendly, and (2) understanding the help in a way that allows them to act. Whether the writer can create prose in the reader’s preferred language or style is, at best, a tertiary concern.

As a writing teacher, I’ve found that structure–arranging information–is the easiest thing to learn about pro writing. What do you think?

If you want to become a better writer (or help someone else become one), we hope you’ll join us for the next Fix This Writing! broadcast on July 18!

Insure readers understand your message with the right content

Workplace readers often say they want short documents. But shorter doesn’t always equal an easier reading experience. Consider these jury instructions:

A fact is established by direct evidence when proved by documentary evidence or by witnesses who saw the act done or heard the words spoken. A fact is established by circumstantial evidence when it may be fairly and reasonably inferred from other facts proved.

Got that? Here’s a revised version of the same content:

Direct evidence means a fact was proved by a document, by an item, or by testimony from a witness who heard or saw the fact directly. Indirect evidence means the circumstances reasonably suggest the fact. Indirect evidence means that based on the evidence, you can conclude the fact is true. Indirect evidence is also called “circumstantial evidence.”

For example, suppose a witness was outside and saw that it was raining. The witness could testify that it was raining, and this would be direct evidence. Now suppose the witness was inside a building, but the witness saw people walking into the building with wet umbrellas. The witness could testify that it was raining outside, and this would be indirect evidence.

When these two versions were tested in a mock trial, the jurors who received the longer version thought it was simpler than those who got the shorter version. And the group with the longer version also scored better on comprehension questions about the content of the instructions. So shorter isn’t necessarily better.

If you haven’t spent much time in a white-collar workplace yet, you likely have little experience writing for readers who know less than you do. Instead, you’ve delivered documents to teachers, who normally know more than you about your content. Plus teachers are obligated to read whatever students write. I promise that won’t be the situation at work! You will have to carefully develop the right information to make your message clear to workplace readers. You’ll have to know your audience well enough to predict what information they need.

Developing informative prose (that means definitions, comparisons, examples, etc.) is briefly explained in Chapter 3 of Revising Professional Writing in Science and Technology, Business, and the Social Sciences (3rd edition). If you’re using the book in an academic setting, you’ll find tons of exercises in that chapter. They’ll help you practice identifying and fixing problems with the supporting details in professional texts. Here are some additional resources:

  • a sample document, including both an original and revised version
  • a brief video tutorial
  • a list of research articles supporting my guidance

Enter feedback in the comments below if you want to suggest how to make the resources more useful.

Sample Document

Read this executive summary for a business plan adapted by me based on a sample available from the Center for Business Planning (businessplans.org).

  • Writer: the owner of a manufacturing company
  • Readers: potential investors (like venture capitalists)
  • Bottom line message: the company is a good investment because they’ve got an innovative product at reasonable cost with high market demand

Here’s a revised version of that executive summary with better content development.

Video Tutorial

The business plan’s executive summary is included in this video about informing readers in workplace documents. My goal is to provide a guide to the essentials, which takes ~13 minutes.

Related Readings

There are posts here at Pros Write that deal with developing effective information for workplace documents. Enter “information” in the search field near the top of this page. If you want to see the research supporting my guidance, you might check out the following sources.

Garrison, L. et al. (2012). Designing evidence-based disclosures: A case study of financial privacy notices. The Journal of Consumer Affairs, Summer, pp. 204–234.

Holmes-Rovner, M.et al. (2005). Evidence-based patient choice: A prostate cancer decision aid in plain language. BMC Medical Informatics and Decision Making, 5(1), pp. 16.

Schiess, W. (2008). The Texas pattern jury charges plain-language project: The writing consultant’s view. Clarity, 60, pp. 23-27.

Plain language in a democracy

Just taking a second to vent my frustration about the lack of plain language on the ballot I read this morning. Here’s a sample.

As someone with an earned doctorate in English linguistics and writing, I would place myself near the top of any chart displaying literacy skills among US citizens. But I had no idea what Alabama Amendment Number 4 meant when I read it.  I had to do some digging to figure out that voting “yes” means:

 Remove all racist language from the Constitution of Alabama!

Today’s ballot included many amendments designed to clean up our state constitution. That’s a worthy effort. I can’t justify my apolitical leanings . . . But it really is hard not to be cynical about government by the people when the people can’t understand what government is saying!