The Reality Behind
Technical Writing
By Kristina
Springer
It’s a Friday afternoon and I’m sitting in a darkened room amidst half a dozen
arguing software developers, each whom, of course, is undoubtedly right in his
own mind and passionate about getting the others to agree. The first draft of
my new manual is displayed on the east wall via projector and the developers are
ripping it apart bit by bit, discussing and changing words, sentences, and
paragraphs. I’m feeling vulnerable, my work being chewed up and sitting
quietly while they discuss what should go where. This is the third day of our
documentation review and we seem to be going at a pace of six pages an hour. The
document is 428 pages, you do the math. It feels like slow torture to me and I
look around the room again, hoping to find an escape route. I am a technical
writer.
One of the most profitable fields in writing is technical writing. And there are
plenty of books, articles, and classes that will teach you the basics-- what
you’ll need to get that technical writing job. You’ll learn structure and rules,
good grammar skills, how to write concisely, and how to translate technical
information into something comprehensible for your reader. You will need to know
your readers well and be able to create a document that is not only visually
appealing but easily useable. This is a small sampling of what you learn in
order to become a technical writer. But what happens once you take that
technical writing job at a software company? What should you expect once you are
a technical writer?
Dealing with Developers
While software developers are some of the smartest and most creative people you
will ever meet, they are also some of the strangest people you’ll ever work
with. Developing is a reclusive task and often attracts that type of
personality. But in order for you to do your job, you need to draw the
information that you need out of them. And you won’t learn this trick from your
average technical writing class. Some developers are so far into their own
worlds that it is difficult to communicate with them. You’ll run into what I
call “tech snobs”: developers so enveloped in talking their techno jargon that a
five-minute conversation with them makes your head hurt. Or, those so intense in
their developing that it is almost impossible to get any time or attention from
them. There are also developers who are just plain shy and won’t want to talk
with you. But, you need these people to do your job so learn quickly how to deal
with them. Be relentless in your quest for information. My best advice is to
find a developer willing to explain things in depth to you and make friends, so
when all else fails when trying to communicate with difficult developers, you
can turn to your friend for help.
Addressing Someone Else’s Writing
Once you are a technical writer, it is likely you’ll be maintaining someone
else’s work. I spent my entire first year as a technical writer just maintaining
an enormous library of 700-page manuals-- updating them with changes and adding
new release material. My writing style was different than the previous writer so
I had to make important decisions, like should I change the existing
documentation to match my style, or concede and mirror the style of the previous
writer? The previous writer’s and my ideas on grammar also varied. For example,
she didn’t introduce bulleted lists with a lead-in punctuated with a colon. I
disliked her style but I had to consider the amount of time it would have taken
me to make that change throughout every manual.
Working with Wacky Deadlines
Your documentation has to be ready to go when your product is ready to hit the
door. Release dates can be moved up or delayed so you need to be on top of what
you are doing. This can get tricky when you’re managing a number of products,
each with their own libraries. When a product is on a set schedule, for example,
quarterly releases, you will have to prepare the documentation on that schedule.
You may size up a project and think it will take you five months. But if you
have only three months to do it you will need to make the changes accordingly to
get the documentation finished on time.
Dealing with Last-Minute Disasters
It’s deadline time and you have all of the manuals ready to go to print. A
senior developer decides to make one small change-- he changes all of the dialog
box headings to headline-style caps instead of the previous sentence-style caps.
Small change for him, big change for you! You now have to re-shoot all of the
screenshots and add them into your documentation. Changes like this can be
thrown at you up until the minute the product hits the door. Be prepared:
re-doing documentation at the last minute weighs heavily on your nerves.
Knowing More Than Just Writing
Along with being a great writer, you’ll need to be savvy with a number of
software programs: online help generating programs like eHelp and RoboHelp, word
processing programs like Adobe Framemaker, and graphics programs like Adobe
Photoshop. Unless you are at a large company with its own graphics department,
you will be the one responsible for taking and manipulating screenshots,
creating flowcharts, diagrams, etc. You will also usability test your
documentation so you need to know the products you are writing for inside and
out. One of the first products I wrote for was a complicated data stream
manipulation tool that utilized its own proprietary coding language.
As you embark on your technical writing career, be prepared for the different
challenges you will face. Unlike any other kind of writing, there are a lot of
people with their hands in the pot, shaping what you make. Bad documentation
generates more calls to technical support which costs money for your company. So
you and your development team need to make the documentation as accurate as
possible. This will call for many drafts and reviews. Reviews can be long,
tedious, and stressful but are necessary to perfect your writing. You knew what
it took to get the technical writing job, now you know what to expect when you
get there.
Kristina
Springer is a freelance writer, technical writer, and a technical writing
instructor at DePaul University in Chicago, IL. She has a
Masters in Writing, also
from DePaul University.
www.kristinaspringer.com
