db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Scott Eade <se...@backstagetech.com.au>
Subject Re: proposal for reorganizing the Torque site
Date Wed, 25 Jan 2006 13:09:15 GMT
Grrr - HD crash killed my reply.

Thomas Fischer wrote:
> Scott Eade <seade@backstagetech.com.au> 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 Eade
Backstage Technologies Pty. Ltd.

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

View raw message