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.

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…

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…

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…

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.

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…

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.