Showing posts with label Writing. Show all posts
Showing posts with label Writing. Show all posts

Tuesday, February 26, 2008

Helping SMEs and reviewers help you

One of the issues we need to guard against is excessive confidence in our own ability. In the past, when managers asked me to estimate a completion time for a project, I almost inevitably came up with a "best case" scenario with very little margin for error. Plus, I usually failed to consider a very important fact when I mentally calculated the time: I need to rely on others for timely information and reviews! How to combat such a mistake? Learn to help others help you!

That's right. Sadly, we can't do it all by ourselves. However, I have found that persistent (but gentle; we need to work with these folks in the future, remember) pressure helps subject-matter experts (SMEs) and reviewers deliver on time. Also, give deadlines for them! Explain when you need to finish the chapter (or document or whatever unit you're working on) and how much time you'll need to make revisions and conduct any further reviews. Most people will understand and, so long as you give them more than a day or two, will work to help you meet your deadline. Just remember that your job isn't in the forefront of their minds, so reminders do not hurt.

As I said, though, be gentle. "Hi! Just wanted to remind you that I need the XX review by the end of tomorrow. Let me know if you have any questions, and thanks again!" is much better than, "Finish the review by tomorrow at 5PM and place it on my desk." Persistent, polite requests are a lot better than demands. If you can tack the reminder onto another request, so much the better, because you won't seem quite so naggy!

Even better, go see the person! E-mails are easy to ignore (or to set aside for later reading... which might or might not happen!). However, in-person reminders are impossible to ignore. Plus, if the SME/reviewer knows that you'll be back and they'll need to look you in the eye and explain why it's not done, they're more likely to do it. If in-person meetings aren't possible, phone calls are good, too.

Let's summarize the tips to help SMEs and reviewers get stuff to you on-time:
  • Be very clear about what you need from them and ask them to confirm that they understand. Sometimes they might not look at it right away, and you don't want to waste valuable time explaining the task when it's getting close to the deadline.
  • Give them more than a day or two. I usually give between 3 and 5 business days.
  • Persistently, but gently, remind them (and ask if they need any information from you) as their deadline approaches. If possible, attach the reminder to another request.
  • Go see them in-person to explain the task and to remind them to complete it. It's difficult to ignore people when they're right in front of you.
Good luck! Create good relationships with your SMEs and reviewers and help them learn to help you, and you'll be poised to demolish your deadlines!

Tuesday, January 8, 2008

"Who" and "whom" are NOT interchangeable!!

Ok, this is just a little diatribe on the use of "who" and "whom". I don't really mind when people just use "who" for everything. In fact, since English grammar relies partly on sentence structure to convey meaning, it doesn't really affect an audience's ability to understand. However, I can't stand when authors and speakers throw "whom" around incorrectly in a vain attempt to sound intelligent. I had someone doing just that earlier today, so I decided to explain when to use it.

To truly understand when to use "who" vs. "whom," you need to understand relative phrases. Relative phrases are really a type of subordinated sentence, whose subject noun phrase is converted to a relative pronoun. They're then used to modify the same noun phrase in a different sentence.

Here's a simple example. We start with two sentences. "The author wrote the book," and, "The author gave a speech." Notice that they share a noun phrase: "The author". We want to turn the first sentence into a relative phrase that modifies the noun phrase in the second. To do this, we replace the noun phrase with a relative pronoun, in this case "who", and move the relative pronoun to the front of the sentence if it's not already there (the relative pronoun is the signal that a relative phrase follows, so it must be first). So, the first sentence becomes "who wrote the book," and our combined sentence reads, "The author who wrote the book gave a speech."

Got it? Once you understand how relative phrases are created, figuring out whether to use "who" or "whom" becomes simple. Use "who" if the noun phrase you're replacing is the subject of the sentence and "whom" if it's the object. Let's modify our example slightly to illustrate. Let's make our first sentence, "The audience adored the author," and leave our second, "The author gave a speech." Now, when we change the first sentence into a relative phrase by replacing the noun phrase with a relative pronoun and moving it to the front of the sentence, it becomes, "Whom the audience adored," and our combined sentence becomes, "The author whom the audience adored gave a speech."

Make sense? That's all there is to it! Now, if only everyone would read this...

(Side note: The discussion on how relative phrases are created will resume when I discuss why I believe it's perfectly OK to end sentences with prepositions. Such suspense, I know!)

Monday, January 7, 2008

"Technical Writer" vs. "Documentation Specialist"

One of my recent managers adamantly opposed the job title "Technical Writer." Instead, he insisted we be called "Documentation Specialists." Now, I've always felt the latter term was cryptic and self-important sounding; I preferred to be a plain technical writer. However, after he explained his reasoning, I began to see that the term "Technical Writer" doesn't really encompass all that we do.

Think about it from a purely descriptive standpoint. When people who have no idea what we do see that term, what do they think? "Technical" connotates, well, complicated information for a highly-educated audience. "Writer" limits the scope of our contribution to simply putting words on paper. Is that the whole of what we do? I think not.

We translate technical content into language that other audiences can understand. We bridge the gap between engineers/programmers and the rest of the world. That translation requires more than just the right words, though. Everything about our documents (or websites or videos or... actually, the choice of the appropriate medium is another facet of our contribution) helps convey the information.

We interview and research; in fact, we have to be experts at dealing with sometimes difficult people to get the information we need. We must be highly proficient with any number of software programs. We're photographers and graphic artists. We're desktop publishers. We're designers. We choose the layout, the colors, the fonts, the organization, the style guide... right down to the size and weight of the paper and the type of binding used to hold it all together. Some of us are even responsible for choosing a print shop, reviewing proofs and pushing the purchase order through.

In short, we do so much more than simply write technical materials. "Documentation Specialist" is a start, but even that title doesn't convey a true sense of everything we have to offer. I'll continue to think about a more appropriate title and let you know if I come up with one. Do YOU have any ideas?

Help! I don't understand active or passive voice (or anything else you're talking about)!

Hey folks, I wanted to point out that this blog, while (hopefully) useful to the casual reader, is really intended for experienced writers. I don't want to alienate my intended audience by including too much detail about concepts that they should already be familiar with. (Note to observant readers: I plan to discuss my stance on ending sentences with prepositions soon!)

Of course, if you're not an experienced writer, don't leave yet! Just know that I won't be explaining every concept I discuss, so you might need to Google a few words or phrases.

Friday, January 4, 2008

Is active voice always the right answer?

I know several writers (usually ones who came into the profession from an engineering or scientific lab environment) who maintain that passive voice is the ONLY way to write technical documentation. "Personal" pronouns, they claim, have no place in impersonal technical documents.

Of course, those of us who went to school for technical writing probably had the opposite drilled into us. Active voice is good! Passive voice is evil! I actually had them personified as super heroes/villains in my mind at one point in my education. The reasoning was that active voice provided a clear "doer" and (less obviously) it removed liability from the technical writer by assigning tasks to specific people (while passive might not clearly state who should do what, which might result in an unsafe work environment depending on the task at hand). Oh, and active voice is a lot more engaging and easier to read, since the sentences are structured in the way English speakers are normally taught to process them (no mental back flips required!).

However, in the real world, while writers should strive for active voice whenever possible, passive voice definitely has its place. I've found two circumstances where I use it often: maintaining focus on a subject and describing errors.

Passive voice lets you put the object of the sentence at the forefront. So if you're writing about a computer disk, for example, "The user should then take the computer disk out of the disk drive" can become "The computer disk should then be taken out of the disk drive." While we have no "doer" in this sentence, we do maintain focus on the disk. (Yeah, it's a simplistic example, but off-the-cuff examples have never been my strong point. In this case, I'd probably just write "Take the computer disk out of the disk drive.")

Passive voice also lets you remove blame from your user when you describe error messages. Why bother? Well, users buy products and thus pay your salary. You want them to feel comfortable with the product, not skittish. Thus, any problem they have shouldn't be described like it's their fault (even if it is). "If you remove the disk while the program is installing, the computer will crash." Yeah, stupid! (That's the message you're delivering there.) Whereas "If the disk is removed while the program is running..." focuses on the action, not the person doing it.

Anyway, just some thoughts on active vs. passive voice. Discuss...