On Wed, Jun 27, 2012 at 5:57 PM, Bob Harner <[email protected]> wrote:
> I'm a really big fan of having one set of docs with "since" and > "deprecated" notations, the way we do it now. If I see something in the > docs that needs improving, I'm only going to bother if there is just one > version to edit. > I think what might be ideal is one set of documentation, but a control/tab for each release, and the page would display just what was appropriate to that page. Anyone carrying around that code in their back pocket? > On Jun 27, 2012 6:37 PM, "Howard Lewis Ship" <[email protected]> wrote: > > > 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 > > > -- 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
