Re: What tech writers do

[Maria Townsley <maria -at- MSD -dot- MEASUREX -dot- COM>]

RE: What do tech writers do?


My company, Measurex MSD, writes software that monitors and controls the
production of paper by mills.  The package includes Order Entry, Production
Planning, Production Tracking, Shipping, and Invoicing.  We do all of this
in a programming language that we invented.

I started here almost three years ago.  I am the first and only tech writer
they have ever had.  They knew they needed good documentation to be
competitive in the marketplace and they knew they couldn't produce the
quality that they wanted. After a long and arduous interviewing process, they
selected me.  (I met with each individual senior programmer I would be working
with and faced a panel made up of several senior programmers and managers.)

Once hired, I was faced with the enormous task of documenting the entire system.
I don't mean just the applications (now numbering about 600), but also the
programming language they had developed, the system structure for the System
Manager (for each platform) the database, the user interface, and
various other auxiliary functions.  They gave me every tool I requested,
anwered every question I asked, prayed that I knew what the heck I was doing,
and waited anxiously for the first pages to come off of the laser printer.

In the past three years, I have designed a format for our manuals, worked with
Marketing to decide the way that they should be packaged and organized,
created outlines for each manual, organized the information, questioned
programmers endlessly, learned how to use the programming tools, learned
everything else I needed to know, wrote endlessly, dragged information and
corrections out of the system experts, tried to remember everything and make
links between things that different people told me, and generally slaved like
a dog.  (Actually my dogs have life rather easy so that probably isn't a very
good comparison.)

They were so anxious for the programming manual, that pages were being
distributed as they were coming off the printer.  After all, our development
team had to teach the other programmers how to program in the language they
developed.  The tutorial was being tested as I was writing it.

That was the first year.  In the second year, I produced rev 2 of every manual.
Because of the massive changes the system went through (doubling the number of
applications, adding tons of functionality and whole new areas of production
tracking and invoicing, ...) virtually every page in every manual was revised.
Additional manuals were created when an application suddenly developed into its
own subsystem.

In this third year, the programming manual will expand from one volume to two.
(The tools are undergoing dramatic changes that will mean all of the examples
and syntax will be changed.)  The number of applications has doubled and
we have ported to another platform (another version of the System Manager's
Guide).  In addition, the entire User's Guide is customized for each site where
we install.  It is also translated in to the local language (French, German,
etc.).  Thankfully, I only have to take the screen captures in the language of
the day, not write the manual in it.  I get about 6 weeks to customize each
User's Guide, including new screen captures, special applications, and
increased functionality.  Now we are looking at going online with the
 programmer's manual and the User's Guide.

As you can see, my job is constantly challenging.  I am very lucky to be the
first tech writer here.  They looked for a subject expert and treated me as
such after they hired me.  (Some companies seem to think that tech writers
are just glorified secretaries.  As a female, I think you face that attitude
more frequently than our male counterparts do.)

Over the years I have developed a few rules that have helped me along the way.

1.  Ask a question once and remember the answer.  No one wants to waste time
talking to someone who obviously doesn't listen anyway.

2.  If you don't understand the answer, make sure they clarify it for you.
You may feel foolish asking for more information about something they think
is simple, but you'll really look like an idiot if you go back to your desk
and write down something that proves you had absolutely no idea what they
were talking about.  There is no profession quite like ours for showing off
any gaps in our knowledge.

3.  Make friends with your programmers.  You'll get a lot more information
from them when you do ask a question if that isn't the only time they see you.

4.  Remember that they have a proprietary interest in every word that you
write.  It is their work that you are talking about.

5.  Take responsibility for your own errors.  Chances are, they didn't lie
to you, you misunderstood.

6.  If they provide input, make suggestions, point out errors, follow up on it.
If I make a change because of something I'm told, I send a copy of the changed
page to the contributor with a big "Thanks!" in the margin.  If they know you
actually do something with what they tell you, they'll be a lot more likely
to tell you something again.  Everyone likes to feel like he did the right
thing.  I've heard Programmer A telling Programmer B that I changed something
in the manual because he noticed it was wrong.

7. Set dates for when you need reviews back.  If he's late, start turning up
at his cubicle looking expectant.  Tell him that all the other reviews are
already in.  Tell him that he has another 2 days or his input won't be
included.  Tell him that Programmer B turned in some information that you
don't think agrees with his firmly held opinion.  Maybe he should let you know
how it *really* works? Be devious if you have to, but get the reviews in!
You can't wait forever.  Remember, the documentation has to be delivered with
the product.

8.  REV CONTROL  REV CONTROL  REV CONTROL   Know what you wrote, when you
wrote it, when it changed, and why.  Track it.  Number it.  File it.  Back it
up frequently.  You'll die by it if you don't live by it.

Obviously, your writing skills are important, but your interpersonal
communication skills are really the most important part of the job.  You can't
write about something if you can't get the information to do it.

That's it.  I have to do some work now.  Let me know if you need any more
long-winded advice.

-maria

DISCLAIMER - Since I'm the only tech writer here, these are all my own
views.