Technical, Business, and Nonprofit Communication Just Got Clearer

Karen CarrollUncategorizedLeave a Comment

Did you know you could be losing money simply because your documentation doesn’t tell your customers what they need to know? A recent survey revealed that 72% of people who called customer support for help with a product said they called because the product’s user guide was not clear. That’s a call your customers should never have to make.

72% of people who call customer support for help with a product say they call because the product’s user guide is not clear.

And that’s why I founded ClearPoint Technical Communication—to help companies communicate more effectively with customers, saving them money in the process.

So how can I help you?

  • I’m a technical writer, editor, and communicator. I develop and write product help content and technical specifications that are clear, concise, and complete.
  • I’m a writing trainer. I train technical, business, and nonprofit writers to make their documentation clear, concise, and complete, too.

What’s my secret? It’s called plain language.

The plain language secret

Plain language is a writing style that makes complex information easy to digest. Studies have shown that even technical information is easier for customers to read, understand, and use when it’s written in plain language.

Here’s what that means for you:

  • For product manufacturers and software companies, that means fewer calls to customer support.
  • For businesses and marketing professionals, that means more sales—and better customer loyalty.
  • For nonprofits, that means grants that get more funding and bylaws that help the organization run more smoothly.

ClearPoint’s technical communication services: Transforming complex information into plain language

In my 20-year career, I’ve worked for companies such as Qualcomm, Intuit, and Credco. I’ve managed documentation projects for everything from product user guides and online help content to API and XML specifications. And I’ve learned a lot–about products, about technical communication, about business. But I’ve learned something else: Any technical writer can tell users how a product behaves or how a system works, but few can show users how to apply that information to the job at hand.

That’s how I save my clients time and money. I write documentation that includes only the information users need. I won’t describe every product feature in tortured detail. Instead, I’ll explain tasks that help users meet their goals.

My writing and editing services include product documentation, including user guides, online help content, and embedded assistance

  • Product documentation, including user guides, online help content, and embedded assistance
  • Technical specifications, including API and XML specifications
  • Grants, bylaws, and all forms of business communication

My services are available on a per-hour or per-project basis

So how can I help you communicate better with your customers? Contact me today to find out.

Or, if you’d like ClearPoint to train your writing staff to use plain language in your documentation, read on!

Plain language training for technical, business, and nonprofit writers

Regardless of their job titles, many people write on the job. Business professionals write project plans, requirement specifications, and marketing materials. Technical writers write everything from user guides to engineering change requests. Nonprofit writers write grants and bylaws.

But few of these otherwise-skilled professionals appreciate the value of communicating clearly with customers. That’s why we offer customizable training programs for writers in almost every professional field.

Customizable programs that produce measurable results

We customize our training programs so that your staff spends its valuable time learning only what they need to know.
Here’s how our process works:

  1. Pre-training assessment: Each program begins with a pre-training assessment of participants’ writing abilities. We analyze your company’s existing documentation to determine where participants need a little extra guidance to write clearly.
  2. Training design: Once we know participants’ strengths and weaknesses, we design a training curriculum that focuses on building up their weaker areas.
  3. Scheduling: Working with your timeframe and available facilities, we schedule the training, book the room, and provide the training materials.
  4. On-site training: Training  lasts 1-3 days, depending on the level of instruction the participants need.
  5. Post-training assessments:
    • At the end of the training, we conduct a simple test to assess what participants have learned and whether they’re ready to apply it.
    • In six months, we conduct a second post-training assessment to make sure participants have continued to apply what they’ve learned to their work.
  6. Individual coaching available as needed: After the training, we offer individual coaching on a per-hour basis for participants who need a little extra guidance.

Which program is right for your team?

For technical writers

  • Beyond the Bulleted List teaches technical writers to write any content more clearly.
  • Trash the Tech Talk helps technical writers sidestep jargon in technical and product documentation.

For nonprofit writers

  • Shun the Shalls: Better Bylaws Using Plain Language shows your team how to write bylaws that express your organization’s purpose and governing principles both legally and clearly.
  • Granted! Your Key to Grantwriting Success teaches grantwriters to communicate their ideas—and win funding—effectively.

For business professionals

  • Ditch the Sales Pitch teaches business and marketing writers to sell their ideas and products without clouding their message with gobbledygook.

Get started with your plain language education today

Are you ready to learn more about plain language but unsure where to begin? Follow me on Twitter, LinkedIn, or the Clear Points blog to get weekly plain-language tips and techniques.

Exciting changes for Write2Help comin’ your way!

Karen Field CarrollUncategorizedLeave a Comment

I want to thank my subscribers for maintaining your subscription even though I’ve not blogged much lately. And I want to tell you what’s coming.

In July of this year, I earned my Masters of Arts degree in English from Northern Arizona University. (That’s the reason I haven’t blogged much these last two years–school!) And now I’m launching my own freelance technical writing and technical-writer training business! Here’s a quick overview; I’ll provide much richer information after the New Year:

My company is ClearPoint Technical Communication. (See my web site at www.clearpointtechcomm.com. Don’t expect great things yet; I haven’t finished the content. On the other hand, if you have suggestions, please send them.) In addition to offering technical writing and editing services, I am developing two training programs for technical writers:

  • The first is called “The Future of Technical Communication is NOW,” which is based on my forthcoming book by the same name. This program teaches technical writers to write product documentation that is clear, concise, and complete using a method I have developed. The program and book also provide workarounds to the challenges many technical writers face when working with Agile development teams. The NOW training program will include a copy of the book, a workbook, and onsite or online-training depending on the needs of the writers taking the class.
  • The second program is tentatively titled “Beyond the Bulleted List: Plain Language in Technical Communication” (BBL for short). Also based on a second book I’m writing, BBL teaches technical writers to apply plain-language principles to the unique challenges that technical communication presents, such as writing user-focused product documentation and keeping technical documentation free of marketing and unnecessary technical jargon. Like the NOW program, the BBL program will include a book I’m writing by the same name, a workbook, and onsite or online training.

If you’re interested in either of these programs or their accompanying materials, it’s not too early to get in touch. Just email me with your questions or to express an interest, and we’ll go from there.

I’m very excited about the opportunities ahead. I’ll be sharing more information after the New Year. In the meantime, Merry Christmas, Happy New Year, Happy Hanukkah, Happy Kwanzaa–in sum, Happy Holidays!

A Podcast about Plain Language

Karen Field CarrollUncategorizedLeave a Comment

I’m no longer a podcast plebe! Click the Play button to hear my first-ever podcast. Of course, it’s about plain language (and my dog Gunther)!

(If you’re previewing this post, click the post’s title to get to the podcast. Then click the Play button.)

 

A Pot Roast in Plain Language: Dinner Is Served

Karen Field CarrollUncategorizedLeave a Comment

In my last two posts I offered a challenge to rewrite a recipe using some plain language techniques, and then I posted my version of the revised recipe. If you’ve paid attention, you’ve noticed that the second version is longer than the first–by over 100 words! So how could rewriting something using plain language make it longer? Isn’t plain language supposed to make something shorter? What gives?

When Longer Is Better

Writers who want to condense what they want to say often use the telegraphic style or load several steps on to one line of text. Our recipe did both. For the intended audience of a cookbook, experienced cooks, this shorthand presents no problem. But for new cooks, like I was only a few years ago, working through recipes like this is exhausting: We often have to re-read steps and double-back to check the list of ingredients as we work.

But using plain language sometimes lengthens a procedure. That’s not a bad thing–as long as  we’re realistic about the level of detail we use.

Realistic Compromises

What do I mean by “realistic”? Let me explain by citing a few steps from a procedure I found in a software user guide.

  1. In the page that opens, type the applicant’s first name in the First Name field.
  2. Press tab to move to the next field.
  3. In the Last Name field, type the applicant’s last name.
  4. Press tab to move to the next field.
  5. In the Street Address field, type the applicant’s street address.
  6. Press tab to move to the next field.

You get the idea. We could debate whether the writer should name each field in each step. (“Type the applicant’s first name in the First Name field.”) But I think–I hope–we can agree that including a step that reads, “Press tab to move to the next field” is tedious and unnecessary when writing procedures.

Dinner Is Served

With realism in mind, I’ve decided that my revised version of the pot roast recipe is too literal. I wanted to bring the embedded and hidden steps forward, and I’ve done that. Now I’ll revise the recipe again–this time to remove words that the reader won’t miss.

Here’s the final version. I’ve used orange text to show what I’ve added or changed and strike-through formatting to show what I’ve cut.

  1. Slice the onions.
  2. Place the meat in the slow cooker and top it with the onions.
  3. Place the onions on top of the meat.
  4. Combine the brown sugar, the soy sauce, and the vinegar in a small bowl.
  5. Pour the mixture over the beef.
  6. Chop the garlic, and grate the ginger.
  7. Add the bay leaves, the garlic, and the ginger to the slow cooker.
  8. Cover the slow cooker, and set it to cook the dish on High for 6-7 hours.
  9. After 6-7 hoursNext, julienne the carrots, slice the mushrooms, and defrost and drain the spinach, if needed.
  10. Spread the carrots, the mushrooms, and the spinach over the beef.
  11. Cover the slow cooker, and let the slow cooker continue to cook the dish on High for 20 minutes.
  12. After 20 minutes Next, remove 1/2 cup of the broth from the slow cooker.
  13. Mix the cornstarch with the broth, and return the mixture to the slow cooker.
  14. Cover the slow cookerand let it continue to cook the dish for 10 minutes more.

These are the compromises I made in this last version. Notice that none of these compromises makes the instructions less clear.

  • I removed the word “the” when I thought it was unnecessary–even though that means using telegraphic style sometimes.
  • I combined the steps that a cook would do almost at the same time, such as placing the meat in the slow cooker and adding the onions on top.
  • I combined other steps that use similar tasks, such as preparing ingredients for the dish, as in step 9.
  • I replaced some words with a shorter word or phrase, as in step 14: “….and cook the dish for 10 minutes more.”

At 163 words, my final version is about the same length as the second one, and it’s just as clear. This version, though, cuts away the fat of the second version while leaving all of the flavor.

Seconds, anyone?

The Pot Roast, Revisited

Karen Field CarrollUncategorizedLeave a Comment

Yesterday I served up a recipe and asked you to slice and dice it to remove any embedded or hidden steps, as well as the telegraphic writing style, from the instructions.

Now that you’ve marinated in the process for 24 hours, it’s time to take the dish out of the oven to see what we’ve cooked up.

Here is the new set of instructions. I’ve given each step its own line, and I’ve added any words necessary to remove the telegraphic style. Look for the blue text to see what I’ve changed in these instructions.

  1. Slice the onions.
  2. Place the meat in the slow cooker.
  3. Place the onions on top of the meat.
  4. Combine the brown sugar, the soy sauce, and the vinegar in a small bowl.
  5. Pour the mixture over the beef.
  6. Chop the garlic.
  7. Grate the ginger.
  8. Add the bay leaves, the garlic, and the ginger to the slow cooker.
  9. Cover the slow cooker, and set it to cook on High for 6-7 hours.
  10. After 6-7 hours, julienne the carrots, slice the mushrooms, and defrost and drain the spinach, if needed. 
  11. Spread the carrots, the mushrooms, and the spinach over the beef.
  12. Cover the slow cooker, and let the slow cooker continue to cook on High for 20 minutes.
  13. After 20 minutes, remove 1/2 cup of the broth from the slow cooker.
  14. Mix the cornstarch with the broth, and return the mixture to the slow cooker.
  15. Cover the slow cookerand let it continue to cook for 10 minutes more.

As I was revising the instructions, I made some stylistic choices. So your version might look a little different depending on the stylistic choices you made. In the last post in the series, I’ll break down what we’ve down and share my thoughts on the process.

 

Practice Your Procedure Writing with Pot Roast

Karen Field CarrollUncategorizedLeave a Comment

I started cooking in my thirties, and I learned through trial by (actual) fire: My kitchen mistakes include several burnt dinners and one small kitchen fire. The kitchen fire was my fault, but I blame my burnt dinners on the people who write recipes. Here’s what I mean.

Recipes use a certain writing style. This style is both telegraphic and obscure. Having blundered because of this style, I think rewriting recipes is excellent training for any plain-language writer.

The Situation

Consider the following recipe. It uses telegraphic style and what I call “embedded” and “hidden” steps—presumably to save space on the page. Experienced cooks use the recipe without incident. New cooks like me, on the other hand, miss steps or do them in the wrong order.

Now, imagine that you’re an experienced cook who just opened a fast-casual restaurant, Your restaurant offers American classic cuisine like beef dishes, potatoes, and biscuits. You’ve just hired a young cook to prep the food while you manage the restaurant, and although your young cook knows the basics—using appliances, working with knives— he has little experience cooking from recipes. To help, you plan to rewrite a pot-roast recipe using plain language. This is the recipe you’ll use:

Pot-Roast Complete*

Ingredients

3-31/z-lb. arm  roast,  boneless

2 large onions,  sliced

1/z cup  brown sugar

1/3 cup soy sauce

1/3 cup cider vinegar

2 bay leaves

2-3 garlic cloves, minced

1 tsp. grated fresh  ginger

1 cup julienned carrots,  matchstick size

2 cups sliced button  mushrooms

2-3 cups fresh spinach leaves,

or 2 10-oz. pkgs. frozen spinach,  drained

2 Tbsp. cornstarch

Steps

  1. Place meat, topped with onions, in slow cooker.
  2. Combine brown sugar, soy sauce, and vinegar. Pour over beef.
  3. Add bay leaves, garlic, and ginger
  4. Cover. Cook on high 6-7 hours.
  5. Spread carrots, mushrooms, and spinach over beef.
  6. Cover. Cook on high 20 minutes.
  7. Mix cornstarch with 1/z cup broth from slow cooker. Return to slow cooker.
  8. Cover. Cook 10 minutes more.

The Challenge

Using the list of ingredients combined with the steps, revise the recipe to fix these things:

  • Embedded steps (Step 1, for example, has an embedded step.)
  • Hidden steps. (Step 7 has a hidden, or implied, step.)
  • Instances of telegraphic style. (For example, “Return to slow cooker” in step 7 uses telegraphic style.)

Instructions

  1. Read carefully both the list of ingredients and the steps.
  2. Identify where an ingredient implies a step that is not in the Steps section.
  3. Identify where the steps use embedded or hidden steps.
  4. Revise the steps using the information you discovered in steps 2 and 3.
    • Use one step for each action.
    • Revise any telegraphic text by adding the necessary “the” or “a.”

Note: You can include the step of “covering” the dish as part of another step, as the recipe writer does in step 6. Be sure to revise these steps to fix other problems, though.

Next

Tomorrow I will add two posts: The first will show the revised recipe. The second will explain what I did to get there.

Have fun!

 

*The recipe “Pot Roast Complete,” by Naomi E. Fast, is from Fix It & Forget It Recipes for Entertaining, by Phyllis Pellman Good and Dawn J. Ranck, 2002, p. 21.

Adopt the User’s Perspective

Karen Field CarrollUncategorizedLeave a Comment

Rolling through Roswell, NM, I saw this ad for a local bank on a billboard:

Lending Should Be Easy. We Make Sure It Is.

The message contains a fundamental flaw. Can you see it?

The message, which is aimed at people who might want a home loan—what the mortgage industry calls “borrowers”— says that lending should be easy.

The problem? Borrowers, the sign’s target audience, don’t lend; banks do. Borrowers borrow. Taken literally, the sign says, “We make sure our part of the process (lending) is easy.” The ad writers probably meant to say, “Borrowing should be easy. We make sure it is.”

For tech writers, writing about a product from the user’s perspective (which the billboard in Roswell does not do) means that we have to use syntax that reflects what the user sees and experiences, not what the system does.

Here are two sentences that illustrate this difference:

The system displays the dialog box.
This sentence describes what the system does.

The dialog box appears.
This sentence describes what the user sees.(In a case like this, you would never write “The dialog box displays,” right? Right? Right?)

You try it. Which sentence is more user-oriented? (I’ve italicized the phrase of difference between them.)

  1. This product enables you to organize your CDs according to title, artist, publisher, or release date.
  2. Using this product, you can organize your CDs according to title, artist, publisher, or release date.

In example (a), the construction “enables you to…” has several problems:

  • It implies that the product controls the user.
  • It makes the product the subject of the sentence.
  • It espouses language from a 12-Step program. (Okay, maybe that bothers only me, but still.)

Do you see what I mean? In this type of writing, the product is the focus of the documentation.

But remember: To the user, the product is a tool; The user needs to know that she is the focus of the documentation, and that the product can give her what she wants.

Example (b) keeps the focus of the text on the user.

  • It implies that the user controls the product—which she does.
  • It makes the user the subject of the sentence.
  • Nary an “enabler” in sight.

I’m not going to lie: Writing from the user’s perspective is hard work. But to quote Wallace Stegner: “Hard writing makes easy reading.”

A Task Is a Task Is a…Procedure?

Karen Field CarrollUncategorizedLeave a Comment

The other day, I got to thinking about tasks and procedures. We had just remodeled our kitchen, and I was flipping through the user manual for our new dishwasher, looking for a section that walked me through the process of washing dishes from start to finish. But the user manual in my hands offered no such trajectory.

Instead, I found the procedures I needed sprinkled under headings that used a mixture of imperative statements (“Start the dishwasher”) and feature names (“Child Lock”). I found the procedure for adjusting the top rack under the heading “Rack Accessories,” the procedure for unloading the dishwasher under the heading “Loading the Dishwasher,” and the procedure for loading the silverware basket in its own self-titled section.

In short, the manual dumped a bunch of procedures at my feet and expected me to organize them into chronological order.

That’s when I started thinking about tasks and procedures—specifically, the differences between them. When I use a product, I have a task in mind: making a phone call, tracking my expenses, and in this case, washing dishes. Many user guides, however, treat procedures like my dishwasher’s manual does: Not as different phases of one task, but as tasks unto themselves.

But is there a difference between a task and a procedure, I wondered? And if there is, does that difference matter to users?

I did some research. According to two popular books on technical communication, a task and a procedure are one and the same.

In The Insider’s Guide to Technical Writing, for example, author Krista Van Laan writes, “As you develop task-based documentation, make sure you clearly define the starting point and the stopping point for each task. In other words, what is the first step the user does to start the procedure? What is the final step that indicates success? Use a consistent format to present each task–a description of the task and its purpose, a lead-in heading, and set of numbered steps are typical” (90). Ms. Van Laan uses “task” and “procedure” synonymously.

And in Technical Writing 101: A Real-World Guide to Writing Technical Content, authors Alan S. Pringle and Sarah S. O’Keefe write that “Procedural information consists of steps that tell a user how to perform a task. Because most content has a great deal of information about how to use a product, you’ll probably spend a lot of time writing procedural information, also called task-oriented information” (103).

So, according to these authors, procedures are tasks, and writing procedures is writing “task-oriented information.”

But a gentleman named Mr. Webster disagrees, and so do experts in fields that address people at work.

Here’s how the Webster’s Encyclopedic Unabridged Dictionary of the English Language defines both a procedure and a task.

  • “procedure: 4. Computers a. the sequence of actions or instructions to be followed in solving a problem or completing a task”  (1542)
  • “task: 1. a definite piece of work assigned to, falling to, or expected of a person; duty. 2. any piece of work. 3. a matter of considerable labor or difficulty”  (1945)

The definition for a procedure implies that a procedure is part of a task. And the definition for a task implies that a task is more involved than following one series of discrete steps.

People who study the field of ergonomics define a task as “a subunit of a job or the group of activities that accomplishes the work objective or job” (Work Rite Ergo: http://www.workriteergo.com/ergonomics/glossary/).

So a task might be a procedure, or it might be several procedures. But to a user like me, a task accomplishes a goal, and any procedures I complete are phases I walk through to get to that goal.

Why does this matter to us—and to our users? Because if we don’t understand the user’s idea of a task, we risk letting the product’s features determine the organization of the document.

That’s what my dishwasher’s user manual did. It’s as if the writer said, “Oh look! There’s that nifty upper rack. Let’s discuss its features and how to adjust it. And the Child Lock feature. That’s important; It needs its very own section.” Not helpful.

What would have been helpful? How about this: One section, or maybe just one procedure, that covered these items:

  • Loading the dishwasher
  • Adding detergent and rinse aid
  • Selecting a cycle
  • Selecting options like Child Lock
  • Starting the dishwasher

But wait, you cry! Where do I describe the differences among the cycle settings, or when to use the safety features, and how to adjust the upper rack, and how to use the rack accessories like those nifty tines that flip up and down?

Here’s what I propose: Either put things such as cycle settings in a simple table beneath the related step, or put the table in an appendix and add one sentence to refer to it within the step. For example, “To choose the cycle, press Normal, Auto, Heavy, or Quick Rinse. For details on these options, see Table 1: Cycle Information.” A user can then either skim the table you’ve included or skip to that section for the information. If she doesn’t need it, she’s free to move on.

Before I etch my philosophy in granite, however, I want to know what you think: Are tasks and procedures the same thing? If not, what’s the relationship between them?

On Plain Language and the Death of Robin Williams

Karen Field CarrollUncategorizedLeave a Comment

Full disclosure: I have clinical depression. The beast came upon me shortly after puberty; medication is the only thing that keeps me well. That said, I have learned to live with my illness the way anyone who has a chronic illness does. Depression is no welcome guest, but these days, it is less foe than fellow traveler. For that, I am grateful.

Others, like Robin Williams, are not so lucky. His death broke my heart. Who could have predicted this?

Events like this ignite the Internet. People tweet; people Like stuff on Facebook; people blog. And then, as the initial howls of disbelief recede into a pensive silence, people opine.

I hate this part.

Why? Because when I read these opinions, I am reacquainted with the breadth of ignorance on topics like depression. And plain language.

Here’s an example. The day after Robin Williams died, a religious man who blogs about the Christian faith–quite well, most of the time–wrote a post called “To Be Happy.” Here’s a paragraph from his post.

“By now we should understand that there are those who seek to find their own happiness in the happiness of others.  The comics among us have so often been tragic characters.  Perhaps they think that if they can make us laugh, they will find joy for themselves.  I won’t pretend to know Robin Williams or understand his demons, but I know that seeking health by making others laugh is a losing proposition.”

I could only sigh. When it comes to the topic of faith and mental illness, my fellow Christians often brandish an ignorance that astounds me.

I commented on the post. I said that depression is not the result of seeking health in the happiness of others any more than cancer is the result of thinking about cigarettes. I wrote that “…Robin Williams’ amazing life ended not because he tried to find his own happiness in making others happy….His life ended because he lost the battle with a debilitating disease.” In other words, I said, “Depression is not a failure to find happiness, but the inability, through no fault of your own, to feel the joy in the happiness you’ve found.”

Other people commented on my post. The blogger did, too. We lapped the usual milestones. Is depression really an illness? (Yes, I said.) Is its cause chemical or environmental? (Either, and often both, I explained.) Does it come on because the victim is doing something wrong, as the blogger’s post had implied about Robin Williams? (No way, I said.) Finally, someone pointed out that the blogger had written, “I won’t pretend to know Robin Williams or understand his demons,” so how could I criticize him for tying the topic of his post to Robin Williams’ death?

(Here’s where plain language shows up.) Because he did so by implication. He used Robin Williams’ suicide as a springboard for his topic. He claimed by word choice his authority on suicide and depression and the causes behind them. Using simple syntax –“I won’t pretend to know…but…”–a writer sends forth his real message under cover of false humility. (“I won’t pretend to know what it’s like to be overweight, but I’ve written an entire blog post about it anyway.” “I won’t pretend to know why people use guns, but here are my Deep Thoughts on the subject just the same.”) The old adage (and plain-language principle) “Say what you mean, and mean what you say” hovers in the air, cringing.

I pointed this out. The blogger said I shouldn’t put words in his mouth and shut down the conversation. Perhaps he’d realized that he had staked out territory he was unprepared to defend.

I’m not in this world to hurt people. I humbled myself and posted an apology on his blog. I said I was sorry that I was harsh (which I was), and that I wished him well (because I do).  He has not replied, but that’s okay; Because whether he accepts my apology or not, I meant it—and everything I said before it.