Re: Software documentation--when to begin?

[Anne Halseytechwriter <ach -at- TOMICHI -dot- STORTEK -dot- COM>]

Peggy Thompson writes:

>  At what point in the fabled software lifecycle do most of you
>  beginning creating documentation? With the alpha system? Beta
>  system? We have a very short turnaround time here for most
>  software documentation projects, lean staffing, and tight
>  funding. We do not find it possible or practical to start with
>  the alpha system. But I would like to hear what the rest of you
>  do and what advantages/disadvantages you run into. Many thanks.

All of us who have been there (and we are legion) empathize
with your situation.  However, I believe it is absolutely
vital that pubs folk be part of the initial design team,
and have their hands on the product from the word go.

If you are brought in late in the fabled cycle - and alpha
phase is much too late - you inevitably play catchup.  You
are also faced with the daunting task of documenting around
poor design (from the user perspective) that would be too
costly to fix once you reach alpha phase.  (We've all been
there, right bunkies?  We've all been told, "Well, your ideas
are good; just wish you'd brought them to our attention sooner.
We'll [come on, you can recite this one with me] ... fix it
in the next release ...")

Advantages to being on the initial design team include - but
are not limited to - the following:

        - playing 'user advocate' during the design phase;
          in other words, making sure that the views of the
          lucky folk who will eventually use (and *pay for*)
          the product are represented during product design

        - getting your hands on the user interface before it
          it is cast in stone; this includes everything from
          the initial boot screen through the menu structure,
          system messages, and help screens

        - being able to assess the software during the design phase
          to determine which documents (both customer docs and
          internal support docs) are needed to superbly document
          the software; if you are involved early, you can have
          influence in arenas that may end up reducing the
          volume of documents you need to generate

        - adopting the role of "user" during early development
          phases; this allows you to provide feedback to the
          design folk concerning functions that might be awkward
          to use

        - being viewed by management as more than a word jockey;
          if the powers-that-be understand that our skills and
          expertise and *interests* range far beyond making
          sure subjects and verbs agree, they'll have a little more
          respect for us

Of course, there are disadvantages.  Probably the biggest disadvantage
is that you increase your level of rework.  IMHO, however, it is
less costly to your company to rework words than to rework code,
to fund help lines and customer service organizations, to lose
future sales because folk were hacked off at the clumsy UI ...

Okay, I'm off the soapbox!  Hope this helps ...

        anne halsey
        senior technical writer, storagetek
        anne_halsey -at- stortek -dot- com