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. 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 >
