[PROPOSAL] New web site organisation

[Vincent Massol <vm...@octo.com>]

Hi,

Here are some ideas about the new Cactus web site layout/organization
that I'd like to propose. 

1/ Here are some general ideas of my view of the Cactus web site:

* Everything is a Topic. A Topic is a small web page focused on a given
subject (and only one subject). For example the "Classpath Howto" is
topic. Etc. Thus the whole Cactus documentation is the sum of all
topics.

Note: This is already what we currently have.

* In addition to Topics we also need Documentation Tracks to help direct
users to what they are looking for. A track can be defined as follows:
  - it has a global intent. For example, a "how it works" tracks would
explain how Cactus works. Another example, a "When to use Cactus" track
would provide information related to when users should use Cactus over
other solutions, in what context, etc.
  - it contains links to Topics relevant for this track
  - it has a roadmap, i.e. it has an ordering of the linked topics

A Track is like putting a filter on top of all the available Topics. It
only shows topics relevant to the track.

* We should have several menus in order not to flood the users with all
information available in the left menu 

2/ Some additional ideas:

* We need a Sitemap page that lists all available topics
(alphabetically) with a short description of the topic

* A search feature would be nice but unfortunately google only allows to
restrict on full domain name and not subdirectories. Of course, we
cannot use any dynamic solution as jakarta.apache.org only supports
static content ATM.

3/ The proposal:

I propose the following 5 documentation tracks and menus. The top level
page would only show the top level menus and when you click on a given
menu item, a new page which describes the track and its content would be
displayed. In addition the submenu for that track will appear in the
left menu. Only one submenu can be displayed at one time.

Downloads
  |_ downloads

Documentation Tracks
  |_ WhatIs Track
  |_ Status Track
  |_ WritingTests Track
  |_ RunningTests Track
  |_ Participating Track

Misc
  |_ Site Map
  |_ FAQ
  |_ Javadocs

Translations
  |_ Korean
  |_ Japanese

Here is how I would link the Topics to the tracks (using the existing
Topic names):

WhatIs Track
  |_ What is Cactus
  |_ How it works (add part about the Spines)
  |_ Features/Status
  |_ Goals
  |_ Roadmap/Todo
  |_ Mock vs Container (to be rewritten as more how Mock and Cactus
complement each other)

Status Track
  |_ News
  |_ Changes
  |_ Features/Status
  |_ Roadmap/Todo
  |_ Tested on
  |_ Cactus users
  |_ Stats
  |_ Bug Database
  |_ Resources
  |_ Mailing lists

WritingTests Track
  |_ How it works
  |_ Migration Howto
  |_ TestCase Howto
    |_ JSP TestCase Howto
    |_ Servlet TestCase Howto
    |_ Filter TestCase Howto
  |_ JSP Howto
  |_ EJB Howto
  |_ Security Howto
  |_ HttpUnit Howto

RunningTests Track (rework of Runner Howto)
  |_ Manual Spine
    |_ How it works
    |_ Classpath howto
    |_ Config howto
    |_ Migration Howto
    |_ IDE Howto
  |_ Ant Spine
    |_ Generic Reusable scripts
    |_ Manual Ant integration
  |_ Eclipse Spine
  |_ Jetty Spine
  |_ Browser Spine
    |_ Runner howto (the section about running from the Browser)
    |_ Tomcat configuration
  |_ Other Spines
    |_ Maven Spine
    |_ JUnitEE Spine
    |_ StrutsTestCase Spine
    |_ JBuilder Spine
    |_ TogetherCC Spine
    |_ Jenerator Spine

Participating Track
  |_ Contributors
  |_ Contributing
  |_ License
  |_ Mailing lists
  |_ Logo Challenge
  |_ CVS
  |_ Coding conventions
  |_ Build results
  |_ Release Checklist
  |_ Build from Sources

4/ Directory structure-wise, I propose the following:

jakarta-cactus/documentation
  |_ xdocs
    |_ topics
      |_ (topic xml xdocs here)
    |_ tracks
      |_ (track xml xdocs here)
    |_ (other misc xml xdocs here)

5/ In term of build implementation, I propose, in a first step, to
migrate our xdocs to the jakarta-site2 DTD (modulo the new features I
had added such as the changes, etc) and to update our stylebook XSL
stylesheet:
- to match the new DTD
- to support the dynamic menus (hiding/showing submenus)

The idea is to prepare ourselves for the next step which will be a
migration towards the new Maven build system. The reason for migrating
our DTD is that all projects in jakarta land are now using this DTD,
which is slightly different from the stylebook one we are currently
using (<s1 title=""> replaced by <section name="">, etc).

What do you think? Comments? Ideas?

Thanks
-Vincent



--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>