Wednesday, April 23, 2008

A techwriter dies and goes to heaven...

and she finds herself at the pearly gates before St. Peter. He looks over her record and decides she is worthy to enter heaven.

"We've upgraded our services recently," he tells her, "so that you now have access to a more personalized heaven experience. Since you are a technical writer, I'll show you several versions of heaven behind some of those doors over there that have been expressly designed to enhance the technical communicator's heaven experience."

"Wow," the techwriter replies with excitement.

"The only problem," St. Peter tells her, "is I just got a text message from the boss and I have to handle it. I'll be back in a few minutes and then I'll give you a tour of your heavenly options."

With that, St. Peter steps away, leaving the techwriter standing in front of three doors. Her curiosity gets the better of her and she opens the first door. There she sees a work station with a bazillion-pixel, high def screen, screaming CPU with graphical coprocessors, loaded with all of the latest authoring tools and a high-speed connection to the UWW (Universal Wide Web). She tries a Google search and instead of getting two-million hits she gets just five, and they are the perfect five.

"This is way cool," she thinks to herself.

She decides to see what's behind the second door. There she finds a cosmic Starbucks. Instead of walls and windows, the table are open to the entire universe and you can almost touch the planets and the stars. Instead of paper cups, the coffee is served in deep blue china mugs. She sees a person putting sugar into her latte (in heaven sugar has no calories) when a tiny paper clip walks across the table and knocks on the mug with a sound of tiny knuckles on glass--tink tink tink!

The paper clip speaks, "I see you're trying to sweeten your coffee, can I ..."

At that point the person fixing her coffee picks up the paper clip, takes a rubber band, and shoots the paper clip out into the vast emptiness of space.

"How cool is that," says the techwriter.

St. Peter hasn't returned yet, so she looks behind the third door. There she sees a technical communicator in a meeting room with developers and she is discussing a user interface being projected onto a screen at the front of the room.

"For one thing," she says to the developers, "you've used 'data base' as two words in the title but as one word in the actual screen. Our style guide says database should be one word."

There is a general round of approvals and one of the developers says, "That's why we need technical communicators on the team."

The technical communicator at the front of the room continues, "And if the user doesn't put the right date format in the date field, you pop up a rather cryptic error message. I think you should just put in some client-side scripting that accepts the user's format and converts it to the format the database requires."

Once again, a general round of approvals and someones says, "Of course, it takes a technical communicator to see it from the user's side. We were too focused on the back-end requirements."

And then the technical communicator says, "I have a report from a usability test we did with real users doing authentic tasks with this UI. I can make the results available to you."

Once again, enthusiasm abounds around the table and someone says, "This is why we need technical communicators on the dev team, they keep us focused on the user, and they have real data to back it up."

At this point, the techwriter hears St. Peter returning and she hurries back to the gate.

"Well," St. Peter says, "let's show you some options for your personalized heaven experience."

"Oh, St. Peter," she says, "I can save you some time. I found my technical communicator heaven; it's behind the third door."

St. Peter looks disappointed. "Oh no," he says, "there's been a misunderstanding. That's not technical communicator heaven; that's the door to developer's hell.

Monday, April 21, 2008

The two most common comma mistakes I see good writers make

As hard as it will be for many of my colleagues to believe, I actually know a couple of grammar rules and even advocate that people follow them.

I just finished a couple of weeks of peer editing and saw good writers making similar mistakes, the same mistakes I see good writers make a lot. The problem, I think, is that our brains know the rules but our fingers ignore them under the pressure of deadlines or when the muse is inspiring us with good content. But for what it is worth, here are the two comma errors I see most often (so if you are guilty of either or both of them, you are in good company).

Punctuating compound predicates as if they were compound sentences

A compound sentence has two complete clauses joined by a conjunction. A comma comes before the conjunction. Example: John wrote the user guide, and Mary edited the installation guide. Two subjects each with their own verb.

A compound predicate has only one subject but two verbs. No comma is used. Example: John wrote the user guide and edited the installation guide. If you absolutely long for a comma in the second example, you merely have to add a subject as in: John wrote the user guide, and he edited the installation guide.

Good writers usually make this mistake when the predicate elements are long, as in: John wrote the user guide that went with the latest version of the TurboPro Archiver, and edited the installation guide that went with the X-Level Wiki Mapper for Linux.

Long, but still a compound predicate and no comma.

Separating a two-item list with a comma

A two-item list does not take a comma. You would never write: You can choose option A, or option B. But as in the first error, good writers confuse themselves when choices get wordy: You can assign users to a category based on the permissions you have granted them in Section 10.4, or based on the profiles you establish in Section 14.6.

Long, but still a two-item list and no comma.

What is getting in the way in both examples is long sentences and the mythical comma rule of "use a comma when the reader needs to take a breath."

No such rule. No NEED for such a rule. None of us has written a technical document so compelling that the reader forgot to breathe. In my own case it's as if I breathe without even thinking about it. My lungs suddenly get hungry for air and wooosh; it just happens. I don't think I've ever heard of a situation where a reader was found blue and unconscious with those around him saying, "Oh my god! If only the technical writer had told him to breathe."

At any rate, be mindful that our fingers and this mythical rule are out to put spurious commas into the otherwise well-punctuated prose of even the most seasoned veterans among us. Keep a watchful eye out.

Wednesday, April 16, 2008

Thursday, April 10, 2008

Get dressed, we're going to a party

On April 22 the Atlanta STC chapter is having its annual awards banquet. Holly Harkness has gone all out to make it a stupendous evening (by that I mean the food will be good, we're going to Maggiano's).

So here's my question: If you are not getting an award, why go to this event? Here are my thoughts:

  • If you only go to church once a year, it's usually on Easter Sunday. It lets you remind yourself what religion you belong to, and you get to see everybody all looking nice. If you haven't been going to STC meetings, this is a good one to go to for the same reasons.
  • An awards banquet is about professional excellence. Hey, that's why you joined a professional society in the first place. This could be the most important meeting you attend. (And if you're not a member, this is a great way to get introduced.)
  • The winning entries are on display. This is the best way to survey what the current standards of "best practices" are.
  • You'll be networking with the thought and practice leaders in the area.

Remember when being a tech writer was fun? Join me at the awards banquet and let's have fun again.