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.

I’ve discovered that I write more conversationally when I’m putting together a script for live training or a tutorial than when I’m writing help or other documentation.

Lately, when I’m writing for training, I’m thinking of actually having a conversation, of talking to a real person. When I write other documents, for some reason I’m not thinking this way. It’s a problem because my user assistance content probably comes out dry as a desert in summer. In addition to not being as conscious of users as I should, perhaps there are a couple of organizational factors affecting my mindset.

› Continue reading…

This week I read a post by Ivan Walsh of I Heart Tech Docs entitled “Who Makes The Most Money—Technical Writers with Strong Language or Deep Technical Skills?” For some reason, his site won’t let me comment, but since it turned out that my reply was somewhat lengthy, it’s better to respond here in my own space instead of imposing on his.

At first, Ivan seemed to be saying that technical skills are more important than writing skills. But I read the post again, and I think he’s saying that technical skills are worth more in the marketplace because they’re harder to develop.

My take is that the reason a developer who does some tech writing gets paid more than the full-time tech writer is because the first guy is still a developer. Developers get paid more than technical communicators most of the time (or all the time, most likely). I think a programmer with some interest or a bit of practice in technical writing getting a job ahead of experienced technical writers may be a signal that management (or HR) doesn’t know what they’re supposed to be looking for in a technical writer.

› Continue reading…

Yesterday, I gave an STC Web seminar on using quick reference guides as part of a documentation set. (I’ve included a picture of how I used my wife’s earwarmer to work around the fact that the speakerphone feature on my new phones is less than desirable.) I answered a number of questions that participants typed into the meeting’s chat box and would like to pass them on. However, I ran into some technical difficulty when I tried to save the chat transcript, so I’m going from memory when writing these questions. These aren’t in any particular order other than the order in which I remembered them. I’ll also do my best to answer, especially now that I’m not on the spot.

What’s your favorite typeface for quick reference guides?

Given the audiences I write for, I anticipate that most of my guides are going to be printed, so I use a serif typeface for body text. I’ve gotten somewhat weary of Times New Roman—so little personality to go along with its readability—so I’ve gone to Cambria. (I know that Word 2007 has heading styles pre-programmed using Cambria, but I usually use sans serif typefaces for headings.) I think Cambria makes a good body typeface.

For headings, I may use Arial, Lucida Sans Unicode, or something similar. I don’t really care for Verdana because it’s so wide. And when you bold Verdana text, it blows up like a balloon.

How do you estimate how long it takes to create a quick reference guide?

That’s a tough question because it varies. How long a guide will take depends on how much of the content is text or images, how much of the content you can use from an existing help system, and so on. If you’re just starting to create quick reference guides, they may take you longer, but as you do more, you’ll probably get faster at them. But each one can take its own tender loving care, so it’s hard to say for sure.

› Continue reading…

After a review of some documents last week, a subject-matter expert told me essentially that one of the first principles of technical writing is to assume that the reader knows nothing about the subject matter.

I saw a couple of things wrong with this, and so I would revise the SME’s statement to make two corresponding and related basic principles of technical writing:

• Know your audience.
• Never assume anything, whether it’s about your audience or the subject you’re writing about.

› Continue reading…

In one application I work on, I recently added some text to the context-sensitive help topic for a screen that allows financial secretaries to make a payment. The text described what to do with a particular control that had been added to the screen.

Because of the many variables involved in making a payment in various countries around the world, this screen has become functionally dense, leading to a help topic that I finally decided had become cumbersome. The bulk of it was a procedure for filling out the information, but in between steps was a lot of “if you need to do X, enter Y” and such things. Some of those extra explanations were only a couple of extra sentences, but added together, it was a lot of content being spewed at the user.

This is a Web application, so we don’t have field-level help. The growth of this help topic led me to imagine that if a user clicked Help for information about one particular field and had to slog through the text in that topic, they wouldn’t get very far before giving up. That much information punching you in the face would be enough discouragement without even beginning to scan it.

I needed a different approach.

› Continue reading…

A huge problem for projects is the lack of a common language between the developers and the users.

When my colleague and I were preparing a presentation for an internal conference on this subject, he said something that has stuck with me. He said, “The goal of the project is to make the user successful.” I added to that: It’s not to write code or validate code. It’s not even to ship a product or make money (of course, this last one is especially true in a non-profit organization). At least, it shouldn’t be these things.

The goal of a project is to make the user successful at what he wants to accomplish.

Go ahead, read that previous sentence a few times. It’s one that would do well to sink in.

› Continue reading…