Other than having a branch (or separate diredtory) for 5.0 vs. 5.1 vs. 5.2, I don't see the approach of having separate documentation for each sub-release as being taxing. Quite the opposite: it seems to be that being sure to document when a feature was introduced, removed (String service id injection, eg.), or changed (ClassTransformation) within the documentation, including keeping notes of what applies to which version, within the same document is only going to lead to confusion, and more rules about documentation. I like having the separate documentation versions. I'm in the middle of upgrading an app right now from 5.0.14 (yup, that old) to 5.1.0.5; it was 5.0.14 for a long time because: a) we had monkey patched/worked around various issues fixed in later T5 releases so there was no pressing need to upgrade and b) the time commitment to upgrade, test, etc. the application was outweighed by the need to fix bugs and add features requested by the client. During the last year+, being able to refer to documentation that is specific to 5.0 was a real boon. So, -1 for single documentation for all versions. :)
Robert On Jun 1, 2010, at 6/13:13 PM , Ulrich Stärk wrote: > By chance I had a conversation with someone experienced in organizing > documentation for software products later today and he recommends to follow a > pragmatic approach. The documentation should always represent the latest > development version and features should simply be marked with the version of > their introduction. In case of changes to previous behaviour old and new > behaviour should be documented, again with a note when the changes were > introduced. Everything more complicated like managing a n-version > documentation is likely to need a lot of rules and discipline and is > therefore likely to not being successful. > > This is more or less what I proposed in the last approach except that it > isn't coupled to a change in our release process. Do you think this would be > feasible? > > Uli > > On 01.06.2010 12:49, Ulrich Stärk wrote: >> 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: dev-unsubscr...@tapestry.apache.org >> For additional commands, e-mail: dev-h...@tapestry.apache.org >> > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@tapestry.apache.org > For additional commands, e-mail: dev-h...@tapestry.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tapestry.apache.org For additional commands, e-mail: dev-h...@tapestry.apache.org
