What does a technical writer do?

A year or two ago I met a fellow writer who was interested when I told him that one can make a good living doing technical writing. He asked me for information, and I went home and found a job description, which I annotated with notes. I sent him the following long screed.

You should only read this if you are interested at all in what a technical writer does. I'm sure that does not include most of my regular readers, but someone looking online for the information might find it helpful.

I found this job description from a job posting someone sent me a couple years ago. It provides a pretty good summary of what a technical writer at a high-tech company does. I will annotate it with numbers like this (1) and give some more details.

Outline (1) and write (2) user guides (3) for our software products, with a focus on concise language and meeting audience needs (4). Write detailed software installation instructions (5), including hardware and software requirements (6) and impact analyses (7). Convert (8) user manuals to online help, editing content as needed (9) to meet the standards of this documentation model. Quickly (10) deliver shorter documents, such as knowledgebase articles (11) and compatibility fact sheets (12), to support internal clients (13) like the Technical Support and Sales departments. Edit and proofread material written by other Documentation team members. (14) Work with Analysis and Design team (15) to examine and understand new product features. Work with Education (16) & Services (17) in the development and production of training materials.

1. Some tech pubs managers want you to produce an outline of your manual before you write it. It can be a useful step to make sure you know what you're doing. Fortunately, the outlines of most software manuals are the same: (I.) How to install the software. (II.) How to configure the software, and how to configure your existing environment to work with it. (III.) How to use it. (IV.) Reference section.

2. Writing -- or "authoring" as people sometimes say -- is usually done in FrameMaker, though some companies use other tools. If you don't know FrameMaker going in, they'll ask if you have done complicated publishing stuff with other software, and this is where you'd mention your expertise in Quark Xpress or PageMaker or something. Writing means filling out the outline you wrote in (1).

3. User Guides. Depending on the size of the product, there are sometimes separate installation manuals, performance guides, troubleshooting guides, etc. etc. People who are just learning the tech writing trade are often given either Installation Guides or Release Notes to do before they let you dig into the other stuff. Release Notes are the "read Me" file that you're supposed to read before anything else. It often contains a lit of "known issues," i.e. bugs they couldn't fix before they ship the software.

4. Meeting audience needs is an important concept in technical writing. You always think about things from the perspective of the audience, i.e. the reader of the manual and the user of the product, and *not* from the perspective of the engineer who gave you the dope on how everything works. In fact, this is really the main thing a technical writer does: translate what the engineer said into something regular people can understand.

5. Installation instructions -- I talked about this already, but I wanted to mention that this sometimes means writing the same instructions several different ways, depending on how many "platforms" (or different combinations of hardware and software operating systems) the company says its software runs on. For example, installing the same software on a Windows system and a Unix system is almost always significantly different.

6. Requirements -- This also gets at the point I just made about platforms. Your manual might tell the customer "You must have installed the 1.5_11 JDK before installing this on your AIX system." See also no. 12 below.

7. Impact analysis -- I'm sort of guessing here -- This probably refers to the "cost," in terms of "overhead," of installing the software or various components of it. For example, let's say you installed Google Desktop on your laptop. You probably know that it uses a certain amount of processing overhead to index everything on your laptop's hard drive. Therefore it has an impact on the performance of your computer.

8. Most companies take a manual authored (there's that verb again) in FrameMaker and use another tool to convert it to another format for online help. The tool commonly used for this is something called Quadralay WebWorks, though there is another tool called RoboHelp that I've never used, but which you see a lot of companies using. The important concept here is "single sourcing," which means that the PDF of your manual and the HTML files of the online help come from the same source, your FrameMaker files. And you can see why this is important -- if you had the same thing documented in two places, that's one too many to try to keep in sync. So tech writing departments try to "single source" as much of their stuff as possible. On the other hand, this is sometimes more of an ideal than a practical goal.

9. Editing content as needed -- This might refer to copyediting, or it might refer to the fact that sometimes the automatic Frame-to-HTML conversion tool is not enough, and you need to tweak the HTML help files to make them look right.

10. Depending on how long it takes the engineers to develop a new product -- or a new version of an old product -- you might update a manual only once every 18 months. On the other hand, sometimes other departments want something lickety split, such as the two things mentioned next.

11. Knowledgebase articles. This is a generic term for "the technical information not found in a manual that is sometimes put online for everybody to read, and sometimes made available only internally, to help customers figure out how to do something." The reason a particular fact or procedure might be found in one of these articles and not in a regular manual is that these articles often document rather obscure behavior of the product that you don't want everyone who reads the manual to know about.

12. Compatibility fact sheets are the things, usually in several tables, that tell you that product A works with operating systems X, Y and Z, but only on Windows XP; and on systems X and Z if it's UNIX running a certain flavor of .... you get the idea. With large enterprise software products this gets very arcane and complex.

13. Internal clients, such as the aforementioned Customer Service, and Technical Support and Sales, mentioned here, are also readers of your work.

14. Other team members. Large companies sometimes have whole teams of writers. I work on a team of eight people plus a manager, and we're documenting the products of one division of a company that sells literally hundreds of products. There are, I think, more than 300 tech writers in the company of 35,000 people.

15. By the Analysis and Design team I suppose they mean Engineering, or maybe the people who give the requirements to Engineering -- in other words, the people who decide what the customer wants in the next version of the product.

16. Education. Large companies, and even small ones, have training classes in their products, and sometimes the tech writers contribute to the training materials -- which are totally separate from the manuals they usually work on. Only in the smallest companies -- like the one I worked at for the last two years that had just fifteen people -- are the writers expected to also write the training courses.

17. Services. Companies have "professional services" departments full of people who go to customers and install and configure the products *for* them, because no matter how simple and clear you make your manuals, the product is often too complicated to install and make work the way the customer wants it to.

Whew. If you got this far without wanting to jab pencils into your eyes, you may have the aptitude to be a technical writer. The next question is, how to get the skills. Since it's hard to gain experience doing things like converting FrameMaker books to HTML help without already being a technical writer, the main way you could make yourself interesting to a manager who might give you a shot is to gain experience doing analogous things. For example, if you've ever done a newsletter for a nonprofit group, a school, a community center or whatever, that involves several important analogous skills, even if you weren't using FrameMaker. If you've ever taught someone how to do a fairly technical thing, that counts for something. Look for opportunities to do the equivalent of creating a technical how-to manual. For example, does the school near your house need a simple how-to guide for its staff on using the email system? If you can find *anything* like this to do, it gives you a writing sample, which is probably the single most important thing you can bring to someone who wants to interview you.

OK, enough already. Best of luck.

That's what I sent the poor fellow. It might have been enough to make him run screaming from the idea of ever being a technical writer. But somebody has to do it.

technorati: technical writing