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 Mon, 16 Jan 2006 12:13:41 GMT

"Thoralf Rickert" <thoralf.rickert@cadooz.de> wrote:

> Hi!
> I think, it's a good idea to reorganize the website. I'd a look and
> two or three comments:
> - When you select the "Documentation" link in the menu you see a lot
> of options in the content (Runtime, Generator and so on). When you
> click on one of this options the menu changes and you see the
> selected option also in the menu. I think this isn't 'ergonomic'.
> First you have to change your focus from the menu to the content and
> then the menu-content changes in a way that you wonder why you've to
> change your focus. Also you've to go back to the first documentation
> content page to reach another tree in the documentation (for example
> when you want to switch from runtime to generator). I think, it's
> better, when the menu shows always all possible (main) options, like
>    Documentation
>      Torque 3.2 Runtime
>      Torque 3.2 Generator
>      ...
>      Older Torque Releases
> ...maybe without version number...

I agree this would be nice, but there is only one possibilities to achieve
this, which would be to regenerate the docs of _every_ old version after
the navigation is changed. This is something I want to avoid, because it
causes endless hassle when releasing a new version (it is already much work
at the moment).
The reason is that every page is generated as a single html page, that is,
the navigation is NOT included externally, but is included at generate time
of the page. So, when you generate the docs for 3.2, you can not include
the navigation points for 3.2.1 or 3.3 in the navigation, because a) you do
not know what the next versions will be and b) you do not want to show them
already in the navigation.
It is not even possible to create a menu called "current release", because
if you generate the 3.2 docs now, it would show in the menu as "current
release" highlighted, but it would stay so if a new version is released.
I.e. if 3.3 is released and included, and you click on "older release ->
3.2" the highlight in the menu would jump to "current version", which I
would consider most irritating.

I have looked at other projects which keep versioned docs, and I have found
none which shows the version in the menu without the menu jumping. For
- http://db.apache.org/derby/manuals/index.html (menu jumps when you click
on a document from the versioned docs)
- http://forrest.apache.org/versions/index.html (versions not mentioned in
menu (the top bar))
As I consider the jumping of the menu very irritating to the user(this is
what we have now), I'd rather use the "not showing the version number in
the menu" option. So the implementation in the proposal (changing the focus
once) is the best non-jumping menu implementation which came to my mind. I
am open to other suggestions.

> - Then - if possible - paths are nice features to view the current
> position on the site. Above the menu there is enough space to insert
> a path like this:
>    Home / Documentation / Torque 3.2 / Runtime
> I think, this could be an additional way to show the user where he is.

This should be possible. I'll go for it if it is not too problematic.

> - The next point is more content based. There is a menu point called
> Wiki which points to a Wiki. I'm not sure if I understand this wiki
> system. Is it a user communication platform or a new documentation
> area. Should the wiki not be part of the documetation tree? And is
> it really useful to have two different documentation systems (I'm
> sure there are some very useful hints in the wiki that are not part
> of the offical documentation and vice versa).

The difference between the wiki and the Torque site is that everybody can
edit the wiki, but only committers can edit the Torque site (plus the code
for generating the Torque site muts be in SVN).
So the barrier to get content in the Torque site is much higher than the
barrier for getting content in the wiki. I would agree that the useful
information in the wiki should go into the Torque site and be removed from
the wiki (to keep it small). So we need a place where every user can put
his comments (the wiki) and we also need a place for the "official"
documentation (the site). I do not see a possibility to incorporate the
features of one place into the other, so we have to use both.

> Also I think, the documetation is really much too maven oriented.
> It's really easy to work with torque and ant. I think, this should
> be more highlighted.

That was what I tried to say by "I did not yet incorporate Greg's
suggestion for an ant user guide". This needs to be written and
incorporated, but it is not very important for the structure(I would put it
in the generator reference, and add text where to find it in the main
documentation page).

  Thanks for giving feedback,


> > -----Urspr√ľngliche Nachricht-----
> > Von: Thomas Fischer [mailto:tfischer@apache.org]
> > Gesendet: Freitag, 13. Januar 2006 21:14
> > An: torque-dev@db.apache.org
> > Betreff: proposal for reorganizing the Torque site
> >
> >
> > Hi,
> >
> > In the last months, I grew more and more uncomfortable with
> > the current
> > organisation of the Torque homepage, http://db.apache.org/torque.
> >
> > The things I like least about it are
> >
> > - when you change to a component of Torque (e.g. the
> > runtime), the menu on
> > the left hand side "jumps" and you cannot get back via the
> > menu to the
> > overview (you have to discover the links in the header)
> >
> > - There is a lot of information scattered in the homepage,
> > but it is very
> > difficult to locate the information.
> >
> > So I went for it and tried to design a new page organisation,
> > where the
> > issues above are resolved. The suggestion can be found at
> > http://people.apache.org/~tfischer/torque-docs/
> >
> > Please have a look and write back whether you like the
> > reorganisation or
> > not. I have rewritten and reviewed a lot of information in
> > the runtime
> > (that was where the chaos was largest because that was once
> > our top-evel
> > page), but of course also the new site is not perfect (though in my
> > opinion it is loads better than our present site). I am
> > grateful for any
> > hint what is missing or wrong (e.g. I did not yet incorporate Greg's
> > suggestion for an ant user guide), but please also judge the general
> > concept.
> >
> > Implementation Details:
> > The method to avoid the jumping menu is to create a "skeleton menu"
> > for the site which is incorporated in every component
> > (basically this is
> > the part of the menu where all items are closed) The disadvantage of
> > this is that it is very difficult to change that skeleton
> > after publishing
> > the site, so I tried hard to create a very general skeleton.
> >
> > I had to create two new subcomponents of Torque for this. One is the
> > tutorial (which in my opinion should live in its own
> > component, anyway),
> > the other is docs-all-components where versioned docs which are not
> > attributable to a single Torque component (e.g. the database
> > howtos) are
> > located.
> >
> > This is just a suggestion. I did not check in any of this to svn.
> >
> >    I look forward to hear your opinion
> >
> >      Thomas
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
> > For additional commands, e-mail: torque-dev-help@db.apache.org
> >
> >
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
> For additional commands, e-mail: torque-dev-help@db.apache.org

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

View raw message