On 12/02/2007, at 1:58 PM, Andrus Adamchik wrote:
> Documentation "branches" are a necessary evil, just like code
> branches (e.g. similarly we often have to apply identical bug fixes
> to 1.2, 2.0, and 3.0 at the same time), and in fact they correspond
> to the *maintained* code branches.
Except that unlike code, we have no diff or merge concepts available
to us. Documentation is completely unlike code also in the sense that
it is helpful to update old documentation for greater clarity even
when the old code is not being touched. Don't you hate it when you
have to use the new documentation because that is the only place to
get the answers, code samples, etc but then you don't know which
parts are relevant and which aren't?
And we have to be realistic: will the old docs ever get updated?
Probably not.
> Going forward we can reduce the number of versions maintained at
> any given moment to just two (1.2 vs. 2.0 vs. 3.0 is a unique
> situation caused by us joining Apache). I.e. when 3.0 becomes
> "STABLE" and 4.0 becomes development release, we will pull 1.2 and
> 2.0 doc sets from the site entirely.
There isn't a need to make old docs vanish completely. Perhaps they
just drop off the menus and are a little more hidden in the site
navigation, but it doesn't affect anything other than taking up a
little more space in the Confluence database.
I guess we will need to see what 4.0 is going to bring before we will
know whether it needs a new branch. If the focus is on a new area,
then perhaps it just needs a chapter heading called "New whizz bang
feature (4.0 only)"... I use another product where every page in the
docs is simply titled with "introduced in version x".
>> Perhaps a tag we attach to the page or part of a page which
>> indicates the version in which that feature was introduced.
>
> This is a good idea to do for the current releases. At the same
> time including the docs for the not-yet-existing features with an
> old release can be confusing. Even worse, some framework concepts
> change over time, with old concepts/API being removed from the
> docs, so stable release users can get the wrong picture.
Yes, you are right. But some of those concepts will probably be more
set in stone in the future as Cayenne matures. Anyhow, nothing needs
to be done until 4.0 or 3.1 is starting to be planned.
Ari Maniatis
-------------------------->
ish
http://www.ish.com.au
Level 1, 30 Wilson Street Newtown 2042 Australia
phone +61 2 9550 5001 fax +61 2 9550 4001
GPG fingerprint CBFB 84B4 738D 4E87 5E5C 5EFA EF6A 7D2E 3E49 102A
This archive was generated by hypermail 2.0.0 : Sun Feb 11 2007 - 22:51:09 EST