Sebastian and I have chatted about this seperately, and I have an issue with the documentation structure ... but I'd like to hear other people's thoughts. Basically, moving the user documentation up a level is problematic.
Currently, the user guide is generated as part of the tapestry-project documentation (the parent of tapestry-ioc, tapestry-core, etc.). Thus documentation changes are coordinated with code changes, and every document page includes the version of Tapestry (5.0.18, 5.1.0.5, 5.2.0.0-SNAPSHOT) that it applies to. It also makes it easier for developers to coordinate code and documentation changes. Moving the documentation up a level (to tapestry-site, what Sebastian has been proposing) has one advantage: the documentation can be updated out-of-cycle; it's no longer beholden to the release cycle for Tapestry versions. But that's also a problem, because the the documentation will tend to be AHEAD of the currently available downloads. That's not the end of the world and perhaps we could introduce some semantic tags, i.e. <introduced-in release="5.2.0.0"> Tapestry can now automatigically frobnicate the groznard via the .... </introduced-in> That would generate a call out next to the paragraph to clearly indicate the release applicable. On another front ... the organization (outside of my above thoughts) appears pretty nice (I still haven't had a chance to look at it in more detail) but this documentation reboot is also a chance to move away from using Maven to generate the documentation. I've had good luck using Ant + XSLT for my personal web sites, but I'd also be interested in looking at other options, including non-Java based ones (Texttile & redbook & those other options). It's just a matter of building out the HTML and transferring it up to Apache, it doesn't have to be Java-based ... and I think a visual refresh, even beyond what Sebastian has accomplished, would be a good thing. On Mon, Sep 21, 2009 at 9:47 AM, Piero Sartini <li...@pierosartini.de>wrote: > +1 for single-click navigation! > > --------------------------------------------------------------------- > To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org > For additional commands, e-mail: users-h...@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
