[FM Discuss] Software versions and user guides

[Andy Oram]

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.)

Andy

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?
>
> Thanks,
>
> Mark
>
>
>
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net