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.

Blogger’s note: A few months after starting my blog, I thought about doing a series of slightly animated videos about me interviewing Gryp, a cartoon gryphon. I based the gryphon image on my site on that idea. Here’s that first interview with Gryp (only slightly edited for this posting). Who knows, maybe there will be more of this in the future.

Ben: Today’s discussion is with Gryp. He’s a gryphon. You don’t see them every day. So, Gryp, just what does a gryphon have to do with technical communication? Is there a connection, or are we just chasing shadows and pixies?

Gryp: I like chasing shadows and pixies. So we can take this in a whole different direction if you want.

Ben: Just answer the question.

Gryp: All right. Take a look at me, and after you’re done admiring my majestically good looks, you’ll notice that I’m half eagle, half lion. You geneticists out there, don’t overanalyze what you see—I am a mythological creature.

Wait… I just realized that raises all kinds of questions about the fact that I’m here right now. But if you want to chase that pixie, find a philosophy blog or a copy of Hamlet’s “to be or not to be” soliloquy.

Anyway, I think you technical communicators usually combine different roles in your work. You’re not just one thing or the other. You’re a writer one hour, an editor the next, then a trainer. The next day, you’re giving input on interaction design and talking about usability. You may be a manager on top of all that.

Ben: So what you’re saying is that a gryphon resembles a technical writer because there is a blending of identities. Do you think that being parts of different things makes you less of each of those things? You’re not entirely a lion, and you’re not entirely an eagle.

Gryp: It doesn’t have to mean that. I’m versatile.

Ben: How so?

Gryp: I can catch prey by chasing it down or dive-bombing it from the air. For you technical communicators, substitute “developer” or “subject matter expert” for prey, and you can see my point.

Ben: Most developers or subject-matter experts would rather not be dive-bombed.

Gryp: Have you ever tried it?

Ben: Can’t say that I have.

Gryp: Shows what you know. Look, you can be very good at the various roles you perform. Some could be minor roles, but others you perform every day. The more versatile you are, the more value you have.

Ben: I have to admit, this blog wouldn’t be the same without you. [To the audience] Thanks for tuning in and listening to a gryphon’s thoughts on technical communication. I’m sure you will never be the same. Until next time!

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…

I’ve been asked what the biggest surprise was for me when I went full-time into the field of technical communication following university graduation. Honestly, not a lot surprised me; I knew how to write procedures, gather information, and use Web, print, and graphics tools. I had even worked in a company environment during a short contract period following my freshman year of college.

So what was the surprise?

Basically that on a significantly sized software development team, no one really knew how to work with a technical writer. So it was up to me to educate them. Problem was, I didn’t know how they were supposed to incorporate me into their team either.

When I worked in that contract position I mentioned, it was on a team of writers and editors. Because we were dealing with content for a website, we interacted with a couple of database administrators, but that was about it. Most of our interactions were with each other and our team lead’s manager.

› Continue reading…

I started to comment on Patty Blount’s post, Kevlar Vests for Tech Writers?, but as sometimes happens, I was waxing verbose and decided to respond in my own post.

Patty asks, “Why are we, as tech writers, so maligned? How can we get development teams to appreciate us more?” I’m going address the “maligned” part more than the “appreciate” part; I think they are two separate discussions. (I may pursue the second issue later.) I’m sure there are many answers to the question as to why project team members may avoid tech writers or develop a negative opinion of us. Much of it probably has to do with how we interact with them.

A few suggestions here, all regarding good people skills.

Respect Others’ Time

First, since much of technical writers do is gather information from other people, be respectful of their time. Don’t ask for a minute unless you literally want 60 seconds of their time or less. If I have what I think is a brief question requiring a brief answer, I ask, “Hey Dan, do you have a few minutes to answer a question, or should I come back later?” They’ll usually be honest about whether they need to finish something first or if they can give me their full attention right then.

Be a Little More Than a Coworker

Second, try to interact with others more than just asking them for information. If you’re early to a meeting, strike up a conversation with a developer about his family or the vacation he just had. That way, you’re seen as a real person and not as just a hound that’s always after something. But remember to be genuine and not seen as exercising that social technique you just read about on someone’s blog.

Relax

Do you think tech writers are viewed as uptight? Do we complain too much?

Do you like talking to uptight, complaining people?

We can take ourselves too seriously sometimes. Of course documentation and user assistance are important, but they’re not the most important thing. Products aren’t created so that there’s something for technical writers to document.

When a developer forgets to tell you about a last-minute change to the UI, take a deep breath. He probably didn’t do it to get on your nerves. Can you imagine a developer saying to himself, “That tech writer bugs me so much, I’ll show him. I’m going to change the order of links in this menu so I screw up all his screenshots. He’ll have to bust his hump to get his changes in by the deadline tonight. *snicker*”

If you can picture this, it’s probably because you have an imagination. But it’s pretty ridiculous. Project teams don’t set out to make the tech writer’s life harder (at least not in my experience, and if you have truly found that developers do this, I’d start looking for another place to work). If you act like they’re doing this, their opinion of you won’t improve. So relax a little and look for ways around the problems you encounter. Don’t play the victim. People usually don’t like the one who always blames others for the pickle she’s in.

Wrap-up

A lot of getting team members to like us isn’t any different than getting anyone else to like us. Just like dogs and cats can coexist peacefully, developers or designers don’t have a natural enmity for technical communicators. You don’t need a T-shirt that says, “Don’t hate me because I’m a technical writer.”

By respecting others’ time, taking a personal interest in them, just plain not taking yourself too seriously, and exercising other good people skills, you’ll probably be more liked on your project team. And you can leave that kevlar vest at home—as well as that “Don’t hate me” shirt.

In my project portfolio, our release manager—the one who instituted release scrums—wants to standardize on release notes across applications. Many of the projects are in a maintenance period, so releases are planned for each project every month or two on something of a rotating basis. These releases will include small enhancements and bug fixes.

One of the challenges of standardizing on release notes is coming up with a release notes process that can efficiently turn out these documents within about a week.

› Continue reading…

I’ve been thinking about user-led learning lately. I have a set of tutorials that we refer to as “tours.” I imagine this term was chosen because the object is to give new users an overview of how to use the various parts of the application to accomplish the main task.

Some Background

Let me give you a bit of history on these tours. Before I was assigned to maintain the project’s documentation, these tours were built as PowerPoint presentations and run through a Breeze engine to create a Flash presentation. (I don’t know if Breeze in that form exists anymore.) Some pages had short videos created in RoboDemo. The presentations contained links to move forward and backward, so the intention was for the user to go from start to finish, similar to taking a tour in a museum: You begin in one place and move through a linear experience.

When I upgraded to the version of Breeze that came out after I took on these files, I found that somehow, multiple videos could play simultaneously. I could start a video on one page, then go to the next page and start that video. I would hear additional mouse clicks. If I went back to the previous page, that video would still be running.

Messy.

I manually moved the content into a new set of HTML pages because I knew that one page loads at a time, so it would be impossible for multiple videos to be running at once. I took the opportunity to learn CSS so I could lay out the pages that way.

› Continue reading…