[FM Discuss] Software versions and user guides
andyo at oreilly.com
Mon Sep 13 09:39:35 PDT 2010
This is a classic tech writing problem that I've never seen solved. I
worked in one computer company where books could contain multiple
versions at once, and you could replace one word if you want in various
versions. XML supports the practice, but it starts to sprout uncountable
versions and becomes a big headache.
No matter what organization you choose, you're left keeping multiple
passages up to date, either in one book or in several. Therefore, I've
always preferred your way 1. It's the cleanest approach from the
reader's point of view. (Few readers want to read simultaneously about
two versions of a tool.)
On 09/13/2010 12:03 PM, Mark wrote:
> Hello Everyone -
> How do we handle different software versions when writing Floss manuals?
> By versions I mean by platform and by numbered release.
> I can think of a few ways to do this:
> 1. Create a new manual for each version. For example, Firefox 3.x and
> Firefox 4.x would have separate manuals.
> 2. Incorporate all versions into a single manual by adding a chapter
> that describes the differences.
> 3. Incorporate all versions into a single manual by describing the
> differences, where they exist, for each feature.
> Suggestion 1 would result in multiple versions of guides that may share
> a lot in common. This could cause extra maintenance work because a
> change to guide A might have to be repeated in guide B.
> For suggestion 2, we would have chapters that might never be read.
> Suggestion 3 might work the best. If you are describing a feature, you
> could describe how it works under Windows, Mac, and Linux.
> Any thoughts?
> Discuss mailing list
> Discuss at lists.flossmanuals.net
More information about the Discuss