Re: Frequent Interim Software Releases (long)

[Kimberly Ferri Cakebread <kim -at- ASPECTDV -dot- COM>]

I think frequent releases is a growing trend.  I've been with my current
employer for 3.5 years.  Since then I've seen more releases than I can
count.  I can't tell you whether it is more likely in a smaller company.
To complicate the matter, we have few specs, no real revision tracking
system, and part of the team, both engineers and writers, is in India.

In terms of producing documentation under these circumstances, I've had to
make the following compromises:

o We've given up the idea of going to press.

o We don't make the manuals very pretty.

o We produce 8.5x11, three hole punch format via docutech or photocopy.

o We provide large binders with generic cover sheets and spines.  We also
provide tabs to divide one book from another (not one chapter from another).

o If a manual revision requires changes to less than 20% of the existing
content, we use change pages instead of printing a whole new book for all
customers.  Change bars are a must.

o We don't keep much documentation inventory on hand.  Each week, I compare
a shipping forecast with current inventory and determine whether we need to
order additional copies of any manuals.  This approach helps us avoid major
scrapping when a sudden revision appears.

o We poll engineers on a regular basis to determine what they are working
on.  That way, we have fewer surprises.

o For software updates that include just one or two changes, we provide
only release notes.  The release notes are unusually detailed, often
including procedures.  Changes get folded into the manuals for the next
major revision.

o We encourage customers to move to our online documentation, which is in
PDF format.

o We enable customers to download manual revisions from our ftp site.

Well, this approach isn't for everyone.  I call it meatball documentation.
But, it's exciting.

Kimberly Ferri Cakebread
Manager, Technical Documentation
Aspect Development, Inc.
kim -at- aspectdv -dot- com


At 03:46 PM 5/21/97 -0600, you wrote:
>How do those of you who write for software companies handle frequent =
>interim releases of the same product? I am convinced that there is a =
>better way of handling it than the method we currently use.
>
>Our situation:
>Version 4.0 was scheduled to release Oct 1. Accordingly, manuals went to =
>press Sept 1. Due to marketing adding new features late in the cycle, =
>release actually happened in Nov. Of course, since the manuals were =
>already at press, we were unable to document the new features except in =
>the helps and readme file.
>
>We needed to reprint new manuals in Dec, so we incorporated all the =
>undocumented features in the new printing. Existing 4.0 customers did =
>not get a copy of the reprint.=20
>
>Then they released 4.0a in Feb. These features were documented in the =
>readme and helps. Then they released 4.0b in April. These features were =
>doucmented in the readme and helps. 4.1 is scheduled to release in July. =
>We are reprinting the manual for 4.1 (adding in all the 4.0a and 4.0b =
>features as well), and everyone who buys or upgrades to 4.1 will get a =
>new manual. Even those who have the 4.0 reprint.
>
>Today, I learned that another (4.1a??) release is tentatively scheduled =
>for Sept.
>
>My questions:
>1) Are frequent releases common in other software companies? Is this =
>more normal for a small company than a large one?
>
>2) What is the best way to handle documenting these changes? Should we =
>print one version of the manual for each main (e.g., 3.0, 4.0, etc.) =
>version of the software and then leave everything else in the readme and =
>helps? Oftentimes changes are not limited to new features--a current =
>feature might change or options might be added to existing dialog boxes.
>
>Any advice you can give will be greatly appreciated.
>
>TIA,
>Melinda Carr
>melindac -at- capsoft -dot- com
>
> TECHWR-L (Technical Communication) List Information: To send a message
>to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
>   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
>  Search the archives at http://www.documentation.com/  or search and
>browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
>
>

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html