Hello,
it is nice to get so much feedback on this.
I set up a second page with static navigation: http://tapestry2.laliluna.de/
Tutorial and Documentation is now collapsed to reduce the total size of
the menu.
The most important thing considering the structure is where to put the
user guide. both options are explained. Could you give an opinion on
this as well? See Howards posting and my initial posting to get an
impression of the pros and cons.
My opinion on a different technology see below.
Howard Lewis Ship schrieb:
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.
For my own website www.laliluna I started to play around with a ruby
based solution using a Ruby template engine and a short script basically
rebuilding what is inside of the Velocity script which is used by Maven.
I am currently using a slightly modified script which needs to be
installed as normal Maven skin.
It is no problem to change this but the current state works as well. It
is not the most elegant not the fastest but it is doing the job. I would
prefer to keep it at the moment and to update the website structure
first, the features page could be reworked, articles for the getting
started section have to be selected. There is probably enough to be done.
--
Best Regards / Viele Grüße
Sebastian Hennebrueder
-----
Software Developer and Trainer for Hibernate / Java Persistence
http://www.laliluna.de
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org
For additional commands, e-mail: users-h...@tapestry.apache.org
