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

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 recorded some voiceover for more Captivate tutorials yesterday, and I made changes to the scripts as I went. Some things just sounded bad when I said them aloud, and others required some tweaking. This reminded me of how reading something out loud makes it easier to find problems with writing.

› Continue reading…

Bookmark It

Hide Sites