OT: Documenting Multiple Baseline Versions of Software

[Jeremy H. Griffith]

On Fri, 21 Dec 2007 10:48:17 -0700, "Lynette Schwend" <lynette at cu.net> wrote:

>Due to the implementation of baseline releases of our software (i.e.
>1.1, 1.2, etc.), our support department is requesting final
>documentation within 60 days of the release to assist with customer
>support and for accountability/liability purposes. 

We don't release software until the docs are ready too.  Yhis
often means that after development is "complete", there's a delay
of one or two weeks before release.  This is a Good Thing; it 
gives us another layer of QA, as the doc production process uses 
the new software.  So we catch a few more problems before they go
out in front of everybody.  ;-)

>To provide some
>history, our techcomm group of three used to provide printed
>documentation and moved on to CD distribution. Currently, we distribute
>CDs to new customers, existing customers facing a complete version
>upgrade (i.e. 1.0 to 2.0) and upon request. We also offer documentation
>access to everyone via our web site. Our development department as a
>whole, has also progressed by providing readmes, preliminary
>documentation and final documentation online, as soon as it is
>completed. 

All good policies.  Between releases, we post betas, for which the
only docs are brief statements in the history.txt file written by
developers.

>With limited technical writer resources, we are considerably
>outnumbered by programmers and testers. However, even if we hire an
>extra resource, we are curious to know how far other companies go to
>provide the most current final documentation between complete version
>releases, as it does require our small group to maintain each baseline
>version (i.e. documentation for 1.1, 1.2, etc.) for CDs and online
>links. Is this realistic? 

Yes.  We don't maintain the docs for previous revisions, only for the 
current one,  If someone asked for earlier docs, we could email them,
but nobody ever has.  We offer an inexpensive subscription process for
upgrades and encourage everyone to stay current.  This minimizes the
support demands on us too, permitting the lower pricing.

>Do other companies provide final documentation
>for "in-between" versions or only for each complete version upgrade? 

We don't distinguish between major and dot revisions any more.  If
it's out (and not a beta), it's a release, and has current docs.

>In addition, we do have a disclaimer stating that documentation from our
>group is subject to change but is that enough to protect us?

Not from the support cost impact.  You'll have customers wondering 
if the difference between the docs and what they see is a feature or 
a bug.  Some will call or write to ask.  You don't want that.  We'd
say six weeks is *way* too long to leave that situation happening.
The docs should match the software, period.

>I appreciate any ideas offered. Thanks!

HTH!

-- Jeremy H. Griffith, at Omni Systems Inc.
  <jeremy at omsys.com>  http://www.omsys.com/