With the upcoming switch from maven-generated documentation to documentation kept in confluence we
should discuss how we will organize the documentation in the future, especially with respect to
versioning.
Currently all work on Tapestry is done in trunk with some fixes being backported to the 5.1 tag,
including documentation. This means that we have several completely independent versions of the
documentation that can be generated on request. If we want to keep it that way, we will have to
somehow artificially version our documentation pages in confluence. E.g. with a parent page
"Documentation" and subpages for each Tapestry version like "Tapestry 5.1", "Tapestry 5.0" and
"Tapestry dev" which themselves again contain independent pages for the different topics like
cookbook, user guide, tutorial, etc.
Another approach could be that we only have the most current documentation in confluence and
whenever a release is published, we export the documentation to html and store it somewhere
alongside the release. This would have the advantage that we don't have to manage several versions
of the documentation but it would also mean that we can't easily amend the documentation of the
released version once work on the development version has progressed.
A third approach could be a mix of the two where we only have the documentation for the current
release and for the current development version in confluence.
A yet another, more radical approach could come hand in hand with a change of how we develop and
release Tapestry. Instead of working towards a fixed set of functionality and release when it's done
(which might take some time) we could begin releasing at a fixed interval, say every two or three
months. That way the current release version and the current development version wouldn't drift
apart that much concerning documentation and possibly long-awaited new features. That way it might
be enough to just have one version of the documentation and mark features not yet in the release
version as such.
There are possibly many other possibilities that I didn't think of and I'd like to discuss these.
What do you think? Have you any other suggestions how to solve this versioning problem?
Cheers,
Uli
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
