db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Thomas Fischer <fisc...@seitenbau.net>
Subject Re: proposal for reorganizing the Torque site
Date Wed, 25 Jan 2006 10:08:40 GMT




Scott Eade <seade@backstagetech.com.au> schrieb am 25.01.2006 01:01:49:

> I have had a quick look at the new version and have the following
comments:
>
>     * When you navigate to the Project Reports for Torque 3.2 Generator
>       and the Maven Plugin a second Project Documentation section
>       appears on the left that confuses things somewhat.

This is a bug. Thanks for noting that. I will remove it.

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


>     * Under Project Documentation, the Project Info links relate to
>       Torque as a whole whereas the Project Reports relate to the site
>       module - I think this is an important distinction.  I suggest we
>       bury the Project Reports under Developer Information with a
>       heading something like "Site Project Reports".

This is a very good suggestion. I'll incorporate it.

    Thomas


---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org


Mime
View raw message