On Wed, Jan 7, 2009 at 9:05 PM, haleh mahbod <[email protected]> wrote:
> Hi, > > The request for "better documentation" was amongst the top ranked feedback > that we received from the user survey in December. I am starting to work on > this (with your help of course). > > > > One of the first steps is to establish a mechanism to have current and up > to date documentation for each release. As it stands today, we have one > version of the documentation that is called the latest [1]. Sometimes the > content is ahead of the latest implementation and we have notes in the docs > that state "not all is implemented yet". This worked fine for a while, but > now that 1.x is maturing and 2.x is staring, it will cause confusion. > > > Can we agree that moving forward we would have documentation per major > (x.x) release? > > > > This means a few things: > > - We need to have a wiki space per release. Let's talk about how > to do this in another thread if there is agreement to go ahead. > > - The "downloads and documentation page" [1] would still point to > the latest release and documentation for quick reference, but the release > pages would need to link to the related documentation as well. In example > [2], the page would include a link to its documentation. This ensures that > the archived releases have their corresponding documentation linked into > them. > > - The "downloads and documentation page" [1] would have SCA java > 1.x and SCA Java 2.x rows. Each pointing to the latest 1.x or 2.x release > and documentation. > > - When a release is finished, a new documentation space gets > started for the next release which will capture the work for the next > release. This is a more proactive approach to collecting information over > the release cycle rather than creating documentation at the tail end of the > release. > > > > Does this sound reasonable? > > > > [1]: http://tuscany.apache.org/tuscany-downloads-documentations.html > > [2]: http://tuscany.apache.org/sca-java-releases.html > That all sounds reasonable to me. It might end up with quite a lot of wiki spaces over time so we may need to check with the confluence admin folks if there's any issues with doing that, but with our current rate of major releases its not going to be a problem in the near future so I say go for it. ...ant
