Feature Article

A Technical Writer's Odyssey
By John Peel

I tend to think of life as a journey, not a destination. Whether embarking on a career, an exotic adventure, or a spiritual quest (some people see these as the same thing), each of us takes a journey through life. Along the way we have good and bad experiences, each one teaching us something about ourselves and our path. Hopefully these experiences make us grow.

However, at some point we reach the end of one path and realize it's time to forge a new one. Such is my case. After 14 years of documenting everything from IBM mainframe software to Network Attached Storage (NAS) servers and Application Program Interfaces (APIs), I've reached a crossroad. The technology bug bit me one time too many, so I'm considering pursuing a more technical career path while still doing freelance technical writing. Meanwhile, I thought I'd share some thoughts and experiences with those of you who are considering a technical writing career. If you're a veteran technical writer, feel free to skip to the last section.

Why Become a Technical Writer?
People become technical writers for many different reasons. A programmer may want to take a break from coding. A journalist may want to take the leap into technical writing. Or a technology buff may want to learn more about what lies ahead. I fell into it while studying computer science at the State University of New York (S.U.N.Y.) College at Fredonia. One morning during my freshman college year, my Pascal programming professor walked into class and said, "There are two important parts to every computer system: the code and the manual." He added that writing user manuals was a viable profession. I spent the rest of the morning thinking things over: natural writing talent plus interest in technology plus desire to make technology available to everyone equals possible career! Later that day he told me how he got his first writing job. His employer wanted someone who knew how to write and had a technical background. His point was that a technical writer didn't need a Ph.D in a technical area, but had to be knowledgeable enough to use what s/he was documenting and explain it to someone else. I knew I'd found my career path.

So I transferred to New York Institute of Technology, which had a new B.S. program in Technical Writing. The program comprised several writing and editing courses, print production workshops, internships, and a choice of interdisciplinary cores. Each `core' focused on a different subject: business, computer science, electrical technology, and life sciences. I picked electrical technology, plus a couple of courses from the computer science core. Two years and two internships later, I graduated in 1988 with honors, ready to take on the world.

So What is a Technical Writing Career Like?
Technical writing is one of the fastest ways to learn about new technology. Instead of reading a book about configuring a new widget, you get to write that book. Whether your company (or client) is developing a new type of network server or a new project management tool, you learn about it before the rest of the world does. You also learn about some of the cool technology behind what you're documenting. One of my first jobs involved documenting a PC-based program that connected a PS/2 to an IBM mainframe. This program had several modules for generating problem reports, connecting to the vendor's mainframe, uploading the reports, and downloading fixes. This program also launched a spreadsheet program or a project manager program from its menu instead of the command line. I used this program as often as possible, which was easier said than done since there was only one PS/2 to share between a dozen writers (we wrote our documentation on IBM 3270 text terminals). After several projects like this one, I became a mini-expert in the products I was documenting and in at least some of the technology behind them. Becoming a technology mini-expert gives you marketable knowledge (good for the resume) and earns you the respect of the engineers with whom you work.

Despite the obvious perks, technical writing has drawbacks. Few people seem to understand how complex technical writing is. It's more than just putting words on a page and printing them. Technical writing requires creativity, technical savvy, planning, and the ability to explain technical concepts to different audiences. In The Art of War, Sun Tzu points out that the best generals plan their victories at headquarters and execute their plans on the battlefield. The same analogy applies to technical writing: all the planning and most of the research is done before you write the first Help topic. And your design (topic titles, cross-references, etc.) is usually based on how a user interface is laid out. Any changes to the user interface impact your document in several places. However, since you know your document, finding the impacted areas shouldn't be difficult. My point is that any changes an engineer makes affect your document in several places, not just one. Of course, tell that to the engineer who changes a dozen field names on several screens and s/he replies that you'd be a great stand-up comedian.

How do you educate your co-workers about technical writing? Try giving a short presentation about technical writing. Explain the documentation process and illustrate how one code change impacts your work. Make analogies between your work and theirs. For example, you can explain to an engineer that a field name change affects every occurrence of that term in a Help system, much the same way that it impacts their code: you need to do a global search and replace, update any cross-references, then regenerate the Help system. Explaining the documentation process in terms your audience understands goes a long way toward gaining their support. You can also recommend some of the books and Web sites listed at the end of this article. You may have to repeat yourself several times, but eventually someone will champion the technical writer's cause in engineering or another part of a company.

Should I Really Take the Time to Learn This Technology?
YES! If you can, take advantage and learn as much as you can about the technology you're documenting. Over the years I've dabbled in different technologies, depending on what I was documenting. If I was documenting an MVS product scheduling tool, I'd watch some tapes on the MVS operating system. If a procedure called for installing a server appliance into a disk enclosure, I'd install the server appliance and configure it, then try upgrading its memory or its boot flash. If I was documenting sample applications for an SDK, I'd interview the engineer, read the specs, then compile and run the applications myself. If a procedure called for pulling a file off a tape, I'd interview an SME, then go into the data center and try the procedure out. If a project involved networks, I'd take a course then build a home network. This last example was a fun project, but my wife wasn't too pleased when her Internet connection kept going down!

What Types of Projects Should I Do?
Do as many different types of projects as you can. The greater the variety, the better. If you're just starting out, you'll have to take whatever projects you can get. Once you gain experience and build a good track record, you may be able to choose your assignments. You'll like some assignments more than others. Shortly after writing my first professional manual from scratch, our department had a re-organization. Some writers were let go, others transferred. So I inherited several update packet projects. Five update packets later, I realized I preferred creating documents to updating them. Since I was one of the rookies in the group, I had to take what work came my way. However, over the years, I've been able to pick and choose assignments that interested me (such as online Help and CBT courses), and mentor junior writers on less interesting projects (such as update packets and Web page edits). Assigning projects to junior writers accomplishes two things: it gives them the experience they need, and gives you experience as a mentor should you be interested in management.

How about Continuing Education?
You never stop learning, especially in technical writing. Whether you're learning a new authoring tool or learning about wireless networks, there's always something new to learn. One one hand, this may seem frustrating since we always find ourselves on a learning curve. On the other hand, it keeps the job interesting. If one is available, take a technology course that relates to what you're documenting. After taking the Cisco ICND course, I had a much clearer understanding of how packets travel up and down the OSI networking layer. This made it easier for me to talk with engineers about Layer 3 switching (routing). The course also explained subnets, which came in handy when I helped the QA engineers reconfigure the routers in their test lab.

Attending conferences is another good idea. Consider going to the annual STC Conference if you can. It's held in different cities each year so check the STC Web site for details. The WinWriters Online Help Conference in Seattle has several sessions on authoring tools, usability, and emerging trends in creating online Help. It also features a peer showcase where you get to show off your work and get useful feedback. The Seybold Publishing Conference in San Francisco includes seminars on the latest publishing trends, bookstalls, and an exhibit hall where companies show off their latest products while raffling off everything from T-shirts to cars. My biggest prize was "Silent Steel," a submarine combat game.

Where to Go from Here?
If you're just starting out in technical writing, you've got an incredible adventure ahead of you. I hope I've provided some pointers to help you succeed in this dynamic field. If you're like me and are standing at a crossroad, you're probably wondering what to do next. First, consider what technology areas interest you. At my last assignment, I spent several months carving a path from Documentation to QA. I spent time learning their tools, attending their meetings, helping write test plans, and reporting bugs. However, after working with a system administrator friend of mine, I'm considering switching to that career path. The big question is how to do this, especially in today's economy.

Consider joining trade organizations in addition to STC, such as the Linux Documentation Project and volunteer. Volunteering gives you exposure to the technical arena and lets you leverage your current skills while learning new ones.You can also seek out a mentoring program. I recently joined Systems Administrators Guild (SAGE), which includes a mentoring program for those just starting out in the field. Of course you can always take a course at a local college or online.

Whatever course of action you choose, try to apply as many of your writing skills as possible while forging your next path. My strategy includes a combination of online courses, personal practice, and mentoring. Will it work? I'll keep you posted.

Useful Resources
Society for Technical Communication
Seybold Seminars and Publications
WinWriters Online Help Conference information
Resources for Technical Writers
Systems Administrators Guild
Software Quality Assurance training and resource site