Clarity trumps probably all other considerations in the actual writing part of technical writing. (I say “probably” because anytime you use such absolutes, you can be quickly proved wrong.) In this particular case, it trumps style.

In my role as a reviewer of department communications, I recently edited a document of brief project status reports. One project’s information contained a line like this:

Project objective: Complete the merger of A’s, B’s, C’s, and D’s operations and technology resources.

Now, the use all those possessives didn’t seem right. I checked my trusty Chicago Manual of Style. CMOS 5.27 states:

Joint and separate possessives. If two or more nouns share possession, the last noun takes the possessive ending. . . . If two or more nouns possess something separately, each noun takes its own possessive ending.

Normally, I’d say that each noun’s possessed thing is separate, so each should have the possessive after all. But then again, we’re talking about a merger of those possessed things. So are they actually separately possessed? Or do A, B, C, and D all possess the merged operations and technology resources collectively?

Dilemmas, dilemmas.

So I removed the possessives. But that resulted in a garden path sentence:

Project objective: Complete the merger of A, B, C, and D’s operations and technology resources.

When you first read the sentence this way, it sounds like A, B, and C are being merged, not things that are possessed by A, B, C, and D. Or even that A, B, and C are being merged with D’s operations and technology resources. So I put the possessive endings back in to maintain clarity over style considerations.

My manager—the second-level reviewer—ended up rewriting the sentence completely, but this little episode illustrated to me how asking what version is clearest can settle other questions.

Bookmark It

Hide Sites

Guest post by Larry Kunz.

Two years ago I hadn’t heard of content curation, and you probably hadn’t either. Now it’s everywhere. The steam of content is turning into a flood. (Brett Swanson calls it the exaflood.)

As a technical communicator, if you’re not already assimilating content from all across the organization—as well as from your customers—you soon will be. In fact, your customers won’t wait to be invited to the party.

This subject fascinates me, and I like to read everything I can about it. I’m noticing something: as the flood of content increases, the flood of content about content curation is increasing too. Blog posts. Slide decks. Webinars. All with their attendant tweets, RSS feeds, and email notifications.

I’m not alone. As I was preparing this piece, I ran across an article in which Ian Greenleigh wrote that he has trouble handling all of the “shiny” new stuff being written about content curation. Like Greenleigh, I have a column in TweetDeck labeled #curation. Unlike Greenleigh, I don’t have ADD—but I still find it devilishly hard to keep up with everything.

› Continue reading…

Bookmark It

Hide Sites

In technical communication circles, we sometimes take ourselves on snipe hunts. Our quarry: getting people to read our documentation.

How do we design it to be attractive? How do we write in a friendly and compelling voice? How can our diagrams be more interesting? How can we turn our documentation into entertainment?

A More Relevant Question

I think we’re past the point of no return in this area. People will read if they want to, but they generally don’t want to read documentation. (Unless maybe you’re including an engaging back story in the manual for your computer game or providing documentation for open source developers so they can be productive in their volunteer efforts.)

This isn’t to say that the questions I asked earlier aren’t important. Nevertheless, I think they’re secondary to the real question.

How do I write for someone who will spare near-zero attention for my material?

› Continue reading…

Bookmark It

Hide Sites

This month we’re transitioning from an old custom document generation application to a new one. Having been the person responsible for training a small group of users, I spent much of yesterday with the person upon whom falls many of the weekly tasks. The project team and our customers wanted to be sure that she’s ready to go when we’re live with the new application and the old one is turned off. (The old one is connected to a legacy database that will be retired soon, so it won’t be available as a backup for very long.)

As we went through the document generation process, this particular user—let’s call her Melissa—let me know where she wasn’t clear on one thing or another. Particularly, she wasn’t clear on what were the exact differences between each of the three screens that the process involves. As we got to the end and Melissa still seemed a little fuzzy, I asked, “Would it be helpful to have a one-page guide that walks through the three basic steps?”

Now, there is a help system. I even have a topic that covers this process from start to finish, involving about ten main steps. However, I could suddenly visualize a page where I matched three steps (with a few substeps each) with the three screens. But the approach here was to give the instructions in their most basic form and leave out a bunch of the details.

› Continue reading…

Bookmark It

Hide Sites

Tom Johnson has me thinking about using story in technical writing. Run a search on “story” on his blog, and you’ll find a long list of results. Because I enjoy fiction writing, I’ve tried to think about how narrative can be woven into documentation more. People connect readily with narrative because it’s part of our everyday interactions. And I think it’s more fun to write. I haven’t written about this as much as Tom, but I’ve written a bit.

I was thinking about it today and had an idea. I think I may have seen this done before, but not much. The concept is creating tutorials around the idea of the learner helping someone who’s stuck. Many people learn better, get concepts cemented in their minds, when they teach those concepts to someone else.

Well, why not work a narrative into an e-learning module that describes a problem a co-worker is having, and then turn things over to the user to guide this character through the next steps? You work in both a story and a way to have the user teach someone else (albeit a fictional character). And it may remove pressure from the learner because the focus isn’t on him or her.

This is certainly an idea that needs some development. If you’re aware of places where this concept has been used in e-learning, please let me know.

Bookmark It

Hide Sites

One of the user education team’s responsibilities is to double as a department communications review committee. We don’t all get together to hash out an announcement or to rip apart someone’s status report. One of us will do an initial edit, and our manager does the second edit before approving it (or not—but we very rarely scrap anything).

We used to take turns meeting with the manager to go over the latest communications together. However, since another role or two was added to the manager’s responsibilities, it’s turned into a more electronic thing. Even back when we were meeting in person, one of my colleagues asked if he could get his assignments ahead of time so he could edit them electronically. At this point, this is mostly how it’s happening.

I’ve fallen out of the habit of printing out help topics or other documents (two pages to a sheet to save paper, right?), though I’ve historically done my editing that way. I printed some help pages out for editing in the same day I edited some department communications electronically, which led me to think about the strengths of each.

So the title of this post is kind of a trick question. I don’t think one method is more effective than the other; I think each has its positive effect in the editing process.

› Continue reading…

Bookmark It

Hide Sites

Do you review and edit the work of a professional writer? Having helped start up a writers’ group within the last few months, I am reminded of what constitutes effective feedback for writers.

Writers get frustrated when someone says, “I don’t like this,” or “This is confusing.” This kind of response isn’t specific enough to do the writer any good. An effective writer is thinking about the effect of the communication on the audience and whether it accomplishes its intended purpose.

Here are a few questions you can answer to give specific feedback that particularly helps a technical writer improve content:

• What’s your first impression? When you look at the presentation of the document, how do you feel? Do the design, typefaces, and so on invite you into the content, or does it turn you away? Do you know where to look first? How does the use of color affect you?
• What do the title and headings tell you about what the document contains? What do they tell you about the document’s purpose?
• Do you find yourself reading any sentences or chunks of text multiple times before you understand it? What kept you from understanding the first time?
• Does the document help you accomplish whatever the title and headings suggest?
• Do the images help you understand concepts or steps better? What sections of text would be improved with images?
• How does the tone of the text make you feel? Does it talk to you on your level?
• Does the document give you all the information you need? Are you left with questions at the end, and if so, does the document tell you where to go to get answers? Or did the document give you too much information?

If you’re a writer yourself and don’t have access to many people to review your work, try leaving the document alone for a while. Then come back and review it with these questions in mind.

Bookmark It

Hide Sites

I’ve been in the technical communication field for about five years now. I’ve made some mistakes myself, and in consulting others tasked with technical writing in the organization, I’ve seen other mistakes. I see patterns that people fall into when they’ve seen tech writing done by other people who aren’t principally technical writers (but they didn’t know that).

As a result, I’ve put together a brief style guide that may help you work that flab off of your writing and replace it with nice, shiny abs. These items go from specific advice on language and wording to some general guidelines.

1: Avoid Telling the User What the Product Allows

Don’t use “X allows you to Y” constructions. Thanks to @kirstyt for pointing this out on Twitter and placing it prominently in my consciousness. Instead of saying what X allows the user to do, say something like “Using X, do Y.”

Avoid Allow’s brother, Can. Don’t tell the user he can do it. Just go straight to telling him how. Almost nothing frustrates me more when looking for help than to be told I can do something but not be told how. Not being told how disproves the statement that I can. This is a quick way to brand your help as useless.

2: Keep Things in the Right Tense

When you have to give some narration about what the product does, narrate in the correct tense. If you instruct the user to click a button, don’t say that her information will be submitted. This suggests that this will happen at some unspecified time in the future. Instead, the information is submitted.

3: Avoid Judgment Calls on Ease or Simplicity

Avoid words like easily (or easy), simply (or simple), and just. These words are a matter of opinion. For more on this, see an earlier post on adverbial crutches and Alan Pringle’s discussion of the cardinal sin of tech writing.

› Continue reading…

Bookmark It

Hide Sites

Once upon a time, a curious little guy named Doubt went to visit his friend. After getting there, Doubt went looking for the kitchen to get a snack.

As he walked down the hallway, he found two doors. The first, which had a plaque that read “Don’t,” seemed after a bit of testing to be locked. The second had a plaque reading “Shouldn’t,” and it stood slightly ajar. Doubt slipped through the doorway and found himself in a small chamber. And it wasn’t the kitchen.

What’s the moral of the story?

I’m working on a little style guide for direct and concise technical writing. One pointer is to avoid the use of should or shouldn’t when what you really mean is do or don’t. Saying something like “shouldn’t” makes it sound optional. In other words, shouldn’t leaves a little room for doubt. Don’t, well, doesn’t. (But notice that Doubt tested the lock on the Don’t door anyway.)

Bookmark It

Hide Sites

If you’re a technical communicator who’s involved in a software development project from its early stages—the way I think it should be—then you may have some input on error messages and other system feedback that users see in the interface. I spent some time last week editing about 1000 messages for another project, and in doing so I came up with a few guidelines for writing them:

1. Give enough information for the user to know what to do next.
2. Use terms that the user understands.
3. Don’t skimp on words. It’s more important that the message be clear than for it to save space. This even includes articles and related adjectives, like “a,” “the,” and “this.”
4. Be consistent with wording and structure. Don’t say “Employee ID can’t be blank” in one place and “The effective date is required” somewhere else.

Bookmark It

Hide Sites