A lot of documentation contains step-by-step directions like this:

1. Click the Add button.
2. In the Name field, enter your first (given) name.
3. Click the Save button.

This is a pretty poor, though common, practice. I’ve committed this offense against readers myself, because it’s so easy to do. Or, rather, it’s so easy to not do the important bit. Here’s what I should have done:

1. Click the Add button. The What’s your name? dialog appears.
2. In the Name field, enter your first (given) name.
3. Click the Save button. The user list appears with your name added to the list.

The difference in the second case is that the steps not only tell the user what she should do, but it also gives her clues about what to expect from each action.

Setting expectations is hugely important, particularly with software. If you’ve ever done usability testing—or even some tech support for mom and dad—you’ve seen what happens when people don’t know what to expect. Someone successfully works through a series of steps, only to stop, unsure whether they’ve done the right thing even when they’ve worked through the steps flawlessly.

This happens when the person working through the steps doesn’t have a way to gauge her own success or failure. This problem is often minimized when working through directions for physical objects, since many of our real-world physical interactions have dramatic feedback. For example, if you wanted to tell someone how to start a car, turning the ignition typically has clear feedback, with simultaneous vibrations, sounds, and visual indicators to demonstrate success and failure.

While most user interfaces provide a minimum level of feedback on interactions (e.g., a button cycles through an animation when clicked), software, with its heavy abstraction from the physical world, frequently cannot provide a more visceral sense of success or failure. With the added complexity of numerous mouse clicks and button presses to complete even simple tasks, it’s no surprise that users get confused even when they’re doing everything right.

And that’s why it’s important to set expectations in your directions. It’s not enough to simply tell your audience what to do, you also have to show them what success looks like.

Occasionally, someone asks me what I do, meaning, of course, what I do for money. Unless I’m feeling especially coy, I say that I’m a technical writer. I’m not sure I could come up with two other words that produce blank stares more reliably. People have no idea what I do.

Through their friends, neighbors, television and movies, I think people have a understanding of a wide variety of professions. Teachers, factory line workers, middle managers, police officers, computer programmers, soldiers, doctors, musicians, and lawyers have all made appearances in film, television, and our lives to the point that most people have at least an idea (however wrongly conceived) of what those people do to pay the bills. As a technical writer, I don’t have the benefit of media* (favorable or otherwise) to help people understand what I do. Superficially, people might think that since writer is in technical writer, what I do might be a bit like what Stephen King does. With the exception of a common tool of English prose, it isn’t.

To break the uncomfortable silence, I usually follow “I’m a technical writer” with “I write directions for software” or “I write computer manuals.” Although this bears some resemblance to the truth, directions and manuals seem to conjure up some uncomfortable associations, namely: Mr. Frustrated IKEA Assembler. And while I’m sure the illustrator behind the IKEA guy can be considered a technical communicator of a sort, it’s not the association I want to make because a) it has very little whatsoever with what I do and b) people hate that guy. If I were to be honest, I would say that I:

• write user guides for nerds people setting up websites,
• write internal documentation for my coworkers,
• record how-to videos,
• write HTML and CSS to pretty up all that stuff,
• program tools to make my work searchable and to analyze how it’s being used, and
• analyze data and review my work to find areas for improvements.

Aside from a light protest of the “No, no, I write directions for computers” sort, I don’t go into that kind of detail. Primarily because most people don’t show an interest, but also because I’m not going to be able to give people a general sense of what a technical writer is by explaining my work.

What I do is divergent from many of my fellow technical writers (not just from apparently everyone else on the planet). In my cohort of English-major technical-writer-types from school, there are few who write documentation for software, fewer still who work with web-related software, and fewer still** who write documentation about web software for technical, non-layperson audiences.

I try to acknowledge the fact that there is a huge variety of work in the field of technical communication. To describe it in the most general terms, technical communication is about standing between technical, domain specific information and making it accessible to people outside of that domain. Frequently, that domain is something technological, such that I openly resent resent Steve Jobs for absconding with one of the best ways in which it’s possible to think of technical communication: it’s being “at the intersection of liberal arts and technology.”

Unfortunately, I can only provide a somewhat limited (and geeky) perspective on what technical writing and technical communication is all about. So I find myself stuck telling people I write software manuals. It’s an affront to my profession in a sense: technical writers add a lot of value in a lot of different and frequently unexpected ways, but I’m not making a case for it.

In an effort to make up for this affront to my profession, forthcoming posts to this blog will attempt to explore some of the nuances of my work. In the coming weeks, I’ve got a lot of posts planned that may give you a greater insight into what it is this particular technical writer does.

* The only exception I know of here is the main character in Zen and the Art of Motorcycle Maintenance. However fascinating and well written the book is, it’s not exactly a useful portrayal for the purposes of describing my job.

** Just one, actually: this guy.