Grrr - HD crash killed my reply.
Thomas Fischer wrote:
Scott Eade <[EMAIL PROTECTED]> schrieb am 25.01.2006 01:01:49:
* For ease of navigation I think it would be a good if the
documentation links for the latest version were always available
directly under the Documentation section heading. As things stand
you have to go back to the Documentation page every time you want
to look at a different section of the documentation - IMO these
should be relatively easy to find rather than hidden. I suggest:
o Documentation
+ Overview [pretty much the current Documentation page]
+ Torque 3.2 [always expanded for the current release,
these should be the 3.2 docs, not 3.2.1-dev]
# Generator
# Maven Plugin
# Runtme
# Supported Databases
# Howtos [not fussed on the split between DB and
Other, this could be done on the target page]
# Tutorial
+ Previous Releases [collapsed by default, could just
link to the Documentation Overview if it is too much
trouble to maintain a list of them here]
# Torque 3.1.1
# Torque 3.1
+ Development [collapsed by default, only present when
docs are being maintained in advance of a release]
# Torque 3.2.1-dev
I agree that this would be a better navigation layout. I also considered
this but it is problematic if the old versions of the docs should be
incorporated in the navigation at later times. (In the moment, they open in
a new window, but this is not very user-friendly in my eyes. On the other
hand, the change of focus is also not user-friendly.)
The problem is that if you include version numbers in the left-hand-side
navigation and want to change their "place" in the navigation (like moving
the 3.2 documentatioin from "Torque 3.2" to "Previous Releases" in your
suggestion if 3.2.1 is released), you would have to regenerate the old
version of the docs (because the navigation is static). Also, in the "old
releases" section, you would have to add the "new old" version to all "old
old" version navigations and regenerate them. Regeneration of old versions
of the site is something I want to avoid at all cost.
Just to explain how the current suggestion is generated (it is checked in
in svn, so everyone can try it):
- run "maven site" in the site, runtime, generator ... components
- chdir to "site/target/docs"
- create a directory "releases/torque-3.2
- recursively copy the runtime/target/docs directory to the subdirectory
"runtime" of site/target/docs/releases/torque-3.2
- repeat the last step with the generator, maven-plugin.....
The only solution I can see to keep the old versions around and keep them
in the navigation is to create one big "site" subproject which keeps every
bit of the documentation (including the old versions). As more versions
will be released, this would become larger and larger. Also not very nice
in my opinion...
What you say makes complete sense and I certainly agree that
regeneration of old versions must be avoided.
Your last suggestion of the one big site subproject might not be as bad
as it at first sounds - it is not like there are a large number of
documents or a high frequency of releases. The trade off is between a
few extra sets of a small number of docs vs. hiding the docs under a
layer of navigation to the inconvenience of the users you are most
likely aiming to help by making these changes.
At the end of the day the structure of the current suggestion is
functional enough - no doubt we would all be happier if the docs for the
current release could be visible in the nav at all times.
Scott
--
Scott Eade
Backstage Technologies Pty. Ltd.
http://www.backstagetech.com.au
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
