A Little Ego Boost

M asked me to review some documents one of her coworkers put together for her company. Not knowing the audience, intent, or how much latitude I would have in editing them, I jumped in intending to do the basics; make sure the document was parallel, check for consistency, review grammar and punctuation, etc. Nothing major. When I was done, I was pleased with the result but had a lot of questions. However, as this was not my project nor did I know the audience, I simply passed the document back to M and let her review my changes.

During the review, the changes I made caused her to ask me a ton of questions -- all questions I had thought of but chose not to ask as this was someone else's project -- and started her on the path of editing my edits as she realized that the document did not go into the depths she was hoping for.

In the end, after her umpteenth question to me and my umpteenth 'item to consider,' she said to me, "Tech writing is hard."

Most companies think having writers on staff is a luxury. Writers are often the first to be let go during layoffs and the last to be rehired. Many companies actually insist that technical writers have experience in programming before hiring them. For example, Microsoft used to insist that all their technical writers have five years of programming experience. Yet, most people point to Microsoft as a primary example of poor manuals and even worse help files.

Technical writers are bridges between the application (be it a program, or some other item, action, or process that needs to be explained) and the lay-people who will use the application. While having knowledge of programming (and any other technical aspect involved in the application, whatever it is) is a good trait to have, too much knowledge can lead to bad technical writing. This is because the technical knowledge gets in the way of the writer's ability to "speak" to the audience. In most cases, the audience is a person with little technical savvy and who just wants to use the application and have it work.

In grade school or junior high, many teachers use the exercise of having their students write out all the steps involved in telling someone who is not from this planet (but, inextricably, knows the language) how to make a peanut butter and jelly sandwich. Most children write something like "Step 1, open the peanut butter jar, Step 2, spread on bread, Step 3, open jelly jar, Step 4, spread on bread, Step 5, eat." However, this skips many, many steps that someone who has never experienced this activity would have to take. For example, what are you spreading it with? How do you open the jar(s)? What does "spread" mean? Where did you get the bread? What kind of bread is it and does it have multiple sides onto which the spreading may occur? Maybe one child out of 100 writes more than about 10-15 steps for this assignment, and that one kid is the one who may have what it takes to be a technical writer.

Assumptions are the killers of good manuals and help files. Each time a technical writer makes an assumption for the audience, it increases the likelihood that someone will not "get it," will become lost or confused, and will not be helped by the information provided. Each time a person reaches this point, one of two things happens: either the person contacts customer support or their opinion of the help provided decreases until they stop using it altogether and they figure out some way of moving on without the knowledge they need (and often resulting in bad data, poor use of the application, and/or errors of various magnitude).

In my last job, I often said the help files and manuals were the user's first interaction with the company at a time when that user was confused and possibly angry. If what we wrote helped them answer their question or solve their problem, the entire company looks good as a result. If it doesn't, then the company looks bad and, if the user chooses to get assistance from support, they are already on their way toward being upset. The best technical writer can, and should, put support out of a job.

A great way to tell the quality of the technical writing involved in a project or application is to check the Index. If the index is one page or less for a standard book-sized manual, you probably will find the manual less than helpful. An index is a microcosm of the technical writer's ability to think about every way in which a user may try to look up or find the information they need within the manual. If the index only tells you the term as that application uses it, the user may not be comfortable or knowledgeable enough to know that term or to know to look up the activity they want to do by that term. So you should always have a more common term or phrase to describe the activity that is a likely way in which a user may name what they want to do. For example, one application I use terms all bullets of any sort as a List. And "List" is the only term by which the index refers to this process. Since I wanted a simple bullet, it took me quite a while before I found this action in the help file I was reviewing. The technical writer who put the help file together should have included terms like "bullets," "numbered lists," and maybe even "special characters" in the index, so people used to terms from other applications could find the same action in this application.

In the end, I got a big kick and a bit of an ego boost out of my wife's assertion that technical writing is hard. Yes, it is! Not everyone can divorce themselves from the technical aspects of what the application does to tell a person the actions they need to take to use it. And, while having technical knowledge is beneficial, it is important not to let that get in the way of making sure that someone without that same knowledge can get the job done.