Version 2 doc linking

[Aristedes Maniatis <ar...@ish.com.au>]

Just a heads up that I've finished linking together all the children  
in the version 2 docs. It is a little time consuming, so I don't  
think I'll do version 1.2, since the pages are identical to version  
2.0 almost everywhere.

For the future, perhaps we should think of ways to not have to  
maintain multiple versions of documentation. Perhaps a tag we attach  
to the page or part of a page which indicates the version in which  
that feature was introduced. After all, we need to update the docs  
not just to add new features, but to explain the existing features  
better. So it would be nice if those improved explanations where  
available to users of all versions of Cayenne. Anyhow, that isn't a  
problem we need to cross until version 4...

Cheers
Ari




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

Re: Version 2 doc linking

[Aristedes Maniatis <ar...@ish.com.au>]

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

Re: Version 2 doc linking

[Andrus Adamchik <an...@objectstyle.org>]

Hi Ari,


On Feb 9, 2007, at 8:29 PM, Aristedes Maniatis wrote:

> Just a heads up that I've finished linking together all the  
> children in the version 2 docs. It is a little time consuming, so I  
> don't think I'll do version 1.2, since the pages are identical to  
> version 2.0 almost everywhere.

Thanks a lot for this work!! I think we are ok with just 2.0 and 3.0  
docs being fully linked on Wiki.

> For the future, perhaps we should think of ways to not have to  
> maintain multiple versions of documentation.

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

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

Andrus