On Wed, Jun 27, 2012 at 10:29 AM, Kalle Korhonen <[email protected] > wrote:
> On Wed, Jun 27, 2012 at 9:02 AM, Massimo Lusetti <[email protected]> > wrote: > > On Sat, Jun 23, 2012 at 1:14 AM, Howard Lewis Ship <[email protected]> > wrote: > >> I'm also concerned about the state of our documentation; these changes > are > >> going to mean far, far more of our {since} caveats; I'm concerned that > our > >> documentation will become a maze of these things! Having the ability to > >> create a parallel branch of the documentation (documentation as source > >> code, not as wiki pages) would be very nice. > > About docs... should we continue to think in terms of Confluence or not? > > Well, we know Confluence, at least with Apache is a dead end. All > projects are supposed to move off of Confluence generated sites by the > end of the year (AFAIK, Confluence itself can still be used, they just > don't want to support resource intensive static page generation from > Confluence pages anymore). I agree with Uli though that Confluence has > served us well - just because the documentation is never up-to-date at > release time. I get what Howard is saying, but I'd take a an > up-to-date documentation with caveats any day over multiple version > specific documentation packages each of them possibly out of date. > Yes, what I'd like would be a structure that lets us publish (even retroactively) a 5.2 version of the docs, a 5.3 version, 5.4 version, etc. As new features are added, they can be added to the documentation (perhaps with a temporary marker, like @since in Javadoc). When a deprecated feature is removed from the code, it could also be removed from the documentation; perhaps will a cross-link to a release where the feature existed. Periodically, we can remove the @since-like annotations; they just become clutter after a couple of releases. However ... I'm super happy with how the documentation came together once we were on Confluence! The contributions by so many people made a huge difference. It seems like the tools we want to use may nudge us towards having the documentation outside the main Git repository, possibly off Apache entirely, so that the community can continue to collaborate on the documentation without impediment. > > Kalle > > --------------------------------------------------------------------- > 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
