When Tom Johnson was considering people’s stereotypes of technical communicators for a presentation, respondents to his survey indicated that, I’d say, between 55 and 80% disagreed that technical communicators are introverted geeks. I agree that we need to be extroverted in order to be most effective.

One of the skills needed in an extroverted technical communicator’s set is the follow-up. I’ve been reminded of this lately as one of my projects is rolling out to offices across the world over the next few months. There is enough involved in that rollout process that the program manager appointed what he called a “rollout manager.” This rollout manager has done much of the necessary work with the stakeholder departments and the office staff to make the rollout happen.

Because I have been working on training materials for the office staff, the rollout manager has been coming to me to keep tabs on my progress. He has also acted as a go-between as the stakeholder departments review and sign off on the materials. We decided to provide a page in the application with links to the materials, and that has taken coordination with our interaction designer and application systems engineers.

Read the rest of this entry »

This week I opened up a Logitech headset at work and pulled out the included quick-start guide. It was one of those that was a single sheet of paper—probably about 24 inches by 18 inches—folded up to fit within the package. The information on the guide was broken into six main sections, only the first two or three of which I was interested in: making sure I would get the thing plugged in and working correctly.

However, the contents of the guide were spread out over the entire front and back side of this large sheet because three languages were included. Being a technical communicator, I couldn’t help critiquing the guide a little bit as I used it. The main stumbling block was that the languages were mixed together: The setup section was given in all three languages, and then the operation section in all three, and so on.

Read the rest of this entry »

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.

Read the rest of this entry »

In one of the applications I work on, we have been dealing with a rollout to different countries where their overseeing offices administer some of the procedures. This has made me ask myself again, “How much of the policies and procedures external to the app do I need to document?”

If policies are at all involved in the procedures accommodated by an application, I find it difficult to completely avoid documenting some of them. Especially when certain practices are preferred out of several options provided in the application. It’s easy to step over the line from strictly talking about how the software works to talking about why it’s designed to work that way. The why is generally to meet policies and procedures.

Read the rest of this entry »

STC’s Intercom magazine published a repurposed post from Gryphon Mountain having to do with what I called the “Unspoken Rule.” The main idea of this post is that I think we as technical communicators ought to afford each other the courtesy of using each other’s materials when the need arises. As the writers, we know how valuable it can be, and if we don’t use it when the need arises, we’re contributing to the prevalent concept that “no one reads it anyway.” By doing so, we shoot our own profession in the foot.

In response, Sharon writes, “I don’t feel guilty about breaking the Unspoken Rule, because I’ve had so many experiences with bad documentation. I give the instructions a fair shot, but sometimes I give up on them fairly quickly. I think that most instructions either are not written by trained technical writers or they are written by people who are technical writers in name only.”

Read the rest of this entry »

The term “technical writer” isn’t one I like much, at least not to describe myself. It calls up an image of someone who sits and writes simple procedures that are printed on sterile-white sheets of paper. (It’s sad when I’m a technical communicator myself, and I still have certain stereotypes in my head.) To me, a technical writer does just what the title suggests—just writes.

To prove to myself that I’m more than a tech writer, I tracked my work time last week, classifying my activities in general categories. Out of a full work week, I spent only about four hours writing, not including emails because I don’t count email-writing as technical writing. These four hours of writing activity included on-the-fly revising that is a standard part of writing for me, so I didn’t break out how much of that time was revising vs. active writing.

Read the rest of this entry »

This post is part of a series on usability and maintainability. At first, meeting the needs of content consumers through usability can seem at odds with meeting needs of technical communicators through maintainability. My purpose in these posts is to discuss how technical communication best practices can satisfy both needs. I’ll use Gurak and Lannon’s usability criteria of users being able to “find what they need, understand the language, follow the instructions, and read the graphics” (A Concise Guide to Technical Communication, 31).

Simple Writing

A style of consistent, concise, simple writing benefits both users and technical authors. In the United States, the average adult reading level is judged to be 8th to 9th grade (ages 13 to 15), and I think it’s safe to assume that readers at higher levels comprehend writing at that average level or lower. (That statistic is cited as coming from the National Center for Education Statistics in a 2002 study, but that source is only referred to and not published online as far as I can tell.)

Read the rest of this entry »