Re: Software documentation--when to begin?

Subject: Re: Software documentation--when to begin?
From: Anne Halseytechwriter <ach -at- TOMICHI -dot- STORTEK -dot- COM>
Date: Tue, 26 Jul 1994 09:02:58 -0600

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

Previous by Author: Brilliant strategies for release notes
Next by Author: Graphics within Help files
Previous by Thread: Re: Software documentation--when to begin?
Next by Thread: Re: Software documentation--when to begin?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads