Further Discussion: Role of Technical Writer

[Moshe Koenig <alsacien -at- NETVISION -dot- NET -dot- IL>]

To all of you who replied to my posting regarding the dilemma I face with
an online Help project I am handling, I want to thank you for your input.
Some of you made assumptions that were not accurate, but then again, I
couldn't provide more background information in the short space available.

In this project, there WAS a detailed documentation plan. Plans are very
useful, provided that the people involved are aware of what actually goes
into producing the documentation. In non-English speaking countries,
however, the technical writer is often "that person who speaks English"
and whose function is less than clear to others. I've encountered some
strange situations over the years, and this situation took a bit from
each of my previous experiences and concentrated them all into one. The
fact that there was a documentation plan was meaningless when you take
into account that the development plan ran a year beyond schedule. I
hear a lot about the technical writer taking a "proactive" role, but
that has nothing to do with writing documentation, which is essentially
reactive; I doubt that even Jeanne Dixon could document a product not
finished.

Of course I was called in as the documentation expert, but the problem
wasn't so simple in reality. The developers come from a different
cultural background, and in general they act as if they're calling
all the shots. I can say that I don't envy the project manager for
having to deal with them, because I heard numerous stories of abuses
that the developers did because they regarded themselves as
indispensable, if not omniscient.

In Windows 95, the style of online documentation changes radically,
which is why I mentioned that the product was Win 3.11; the use of
segmented hypergraphics, excessive graphic inserts, etc., are very
characteristic of pre-Win 95 online Help but are used sparingly in
Win 95. The product makes use of tip helps and status bar messages,
which led me to feel that a separate topic for each menu option
was overkill, not to mention excess baggage for an already top-heavy
online Help file.

Perhaps it's a deficiency in my own schooling, but from the moment
I began writing online Help, I have heard the term "task-oriented"
as a keyword. An engineer may be able to use an online Help that
just describes the menu options and the dialogs without any clue
as to how to do something with them; users need more help.

The thing that perturbs me is that the project manager seems to have
entered Panic Mode; he is overly concerned with the excessive delay
in the product's release, and he doesn't want to hear of further
delays. I don't see designing intelligently conceived Help as an
unnecessary delay. I don't feel that I should give in to demands from
people who aren't sensitive to user needs (the developers), nor
should I be occupying myself with context sensitivity hooks,
especially when you consider that the situation requires me to
finish a reference guide after I finish the online Help. The
developers won't be handling that for me; it's my exclusive
headache.

I might add that I'm not a full-time employee on this job; I'm
a freelancer with other obligations. I've got one major
company wanting me to come on board as a full-time employee,
and if the price is right, I'll do it, simply because I've
tired of the sort of struggle that this project has created.
I did not mention the way that I get dozens of calls, faxes,
e-mail messages, every day regarding the progress on the
project, something that weighs too heavily on me as is. It
also doesn't help that my brother died when I was after the
alpha stage of the project; the tragedy slowed me down
considerably, and because I was working on it literally
up to the moment he died, I also have some emotional
baggage to overcome. I'm trying to get perspectives from
others so that I don't act rashly; I'm aware that I'm not so
objective.

The truth is, however, that when this product hits the market,
I'm sure you'll all know about it and feel the way I did about
it. If I hadn't believed in it so strongly, I wouldn't have
begun to put up with all this grief. Most of my projects have
been get-the-information, write-a-draft, get-the-feedback,
make-the-corrections, write-a-new-draft, get-approval, publish-
the-documentation, and no more; it's rare to feel identification
with a product as you document it, which may be the thing that
clouded my judgment somewhat. From the standpoint of cost
efficiency and meeting deadlines, this project would rank last.
However, the end product should be something that everyone who
stuck it out would be proud to have taken part in its development.

Your comments are more than welcome. I'm really in this up to my
neck. The only time in my life I've backed out on a project was
when my brother died, and it was probably the only time I could
have done so without facing a firing squad. This time I'm just
not sure.

- Moshe

                  TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send administrative commands
         ALL other questions or problems concerning the list
       should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-