Software Documentation

[Joanne Tait <jtait -at- SHOWBASE -dot- COM>]

Hi List,

From all of you software documentors out there, could I get some
insights into the various types of documentation that accompany software
releases.  We are beginning the process of setting up a procedures
manual as well as scheduling a current project.  We are trying to define
the tasks involved in a beta release.  Until I arrived, what
documentation there was had been hired out . . . now I'm a lone, newbie
writer ('nuf said).
{:-}

Please reply to me off-list and I will try at some point to compile a
collection for interested parties, if any.  BTW, I love this list.

*****
First question(s) - when do you write a whole new manual or simply write
an addendum to the existing manual?  Do major version numbers (i.e. v1.5
to v2.0) dictate the need for a new book or is it the actual number of
pages to be rewritten/added that determines this?

Second question - am I correct in my following definitions/assumptions:

Read Me file:  a text file that accompanies the executable installation
file (that is, not compiled in install .exe file) and contains
installation instructions

Release Notes:  a text or pdf file that addresses  concerns regarding
knownsoftware bugs and describes fixed bugs from earlier versions and
workarounds

Addendum (to the manual):  documents minor changes to the existing
documentation (i.e. a new button on a dialogue box, etc.), and any
errata(e/s/um(s))

Revision (to the manual):  documents major revisions to only one or two
isolated sections of the manual (does not effect the entire manual)

Last question (really):  do you update the on-line help for each release
or only for major ones?  Frankly, I have an application whose on-line
help is not quite up-to-date with the software and it does get a little
frustrating at times (have I just answered my own question?).

TIA (cha cha cha)

Joanne Tait
Technical Writer/Webmaster
ShowBase Inc.
>21A Park St.
>Aylmer, Quebec
>Canada  J9H 4J6
>Tel: 1 800 685-9888 ext. 247
>Fax: (819) 685-2244
>E-mail: jtait -at- showbase -dot- com
>http://www.ShowBase.com
>

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=