It would be nice if there was an easy way to mark a paragraph of wiki text as "Removed in 5.2", "Added in 5.3", etc. Something that would put a visible marker into, say, the right hand gutter of the page, next to the marked paragraph.
On Wed, Jun 2, 2010 at 12:50 AM, Ulrich Stärk <[email protected]> wrote: > Managing a version of the documentation for each release in confluence is to > the contrary quiet cumbersome. With every new release we need to *manually* > copy the existing documentation to a new place. Page by page. Unfortunately > there is no easy way to just create a copy of a page and all its subpages at > once. All we could do is export the whole space and import it as a new one. > This would mean one space for each version of the documentation and this > will make administering the whole thing very complex. In addition it means > that fixes to the documentation will have to be done in multiple places if > we want to keep the docs for a released version up-to-date as well. I fear > that nobody is willing to go through that hassle meaning that the > documentation will be that as of the time of release. Then there is no > reason to keep multiple versions, a static export from the time of release > would be enough. > > Uli > > On 01.06.2010 22:54, Robert Zeigler wrote: >> >> 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 l > > ast 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: [email protected] >>>> For additional commands, e-mail: [email protected] >>>> >>> >>> --------------------------------------------------------------------- >>> To unsubscribe, e-mail: [email protected] >>> For additional commands, e-mail: [email protected] >> >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: [email protected] >> For additional commands, e-mail: [email protected] >> > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > > -- Howard M. Lewis Ship Creator of Apache Tapestry The source for Tapestry training, mentoring and support. Contact me to learn how I can get you up and productive in Tapestry fast! (971) 678-5210 http://howardlewisship.com --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
