[FM Discuss] Software versions and user guides

[Michael McAndrew]

Hi,

Here's how it was with CiviCRM.  This might be tangential since our
decisions were pragmatic rather than technical but maybe useful
background...

We wrote the first manual in a sprint when version 2 was out.  About a year
later when version 3 was out, we had another sprint.

Our motivation in the second sprint wasn't only to cover new functionality
in version 3 - in fact there were some big holes left over from the first
manual.  And we wanted to improve already existing chapters, etc.

So we branched the book, worked on the second edition and didn't back port
any of our improvements back to the first edition.  We've now hidden the
first edition and I personally would recommend that anyone (regardless of
the version they are using) should use our second edition.

In the end, both books are general CiviCRM books that happen to be about a
specific version because they were written when that version was the latest
version.

It would be v. hard for the CiviCRM documentation community (which is quite
small) to keep to date two differerent versions of the book and actually, we
don't see it as that important.  But that is down in part to the style of
the book (the content of which is not that closely to a version of the
software), the nature of CiviCRM as a software project (quickly evolving)
and the CiviCRM community (which isn't massive).

Anyway, this doesn't really answer your question but that is because (like i
said above) for pragmatic reasons, we didn't need to.  Maybe that is helpful
for you :)

Michael




On Mon, Sep 13, 2010 at 5:03 PM, Mark <mark.brennan at gmx.com> 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
>
>


-- 
Michael McAndrew
07817 802299 (mobile)

Third Sector Design Ltd.
http://thirdsectordesign.org

For support, email support at thirdsectordesign.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.flossmanuals.net/pipermail/discuss-flossmanuals.net/attachments/20100913/a57198d4/attachment.htm>