tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Howard Lewis Ship <hls...@gmail.com>
Subject Re: New branch: 5.4-js-rewrite
Date Thu, 28 Jun 2012 16:09:03 GMT
On Wed, Jun 27, 2012 at 5:57 PM, Bob Harner <bobharner@gmail.com> 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" <hlship@gmail.com> wrote:
>
> > On Wed, Jun 27, 2012 at 10:29 AM, Kalle Korhonen <
> > kalle.o.korhonen@gmail.com
> > > wrote:
> >
> > > On Wed, Jun 27, 2012 at 9:02 AM, Massimo Lusetti <mlusetti@gmail.com>
> > > wrote:
> > > > On Sat, Jun 23, 2012 at 1:14 AM, Howard Lewis Ship <hlship@gmail.com
> >
> > > 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: dev-unsubscribe@tapestry.apache.org
> > > For additional commands, e-mail: dev-help@tapestry.apache.org
> > >
> > >
> >
> >
> > --
> > 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

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message