Ian Dickinson wrote:
Hi Paolo,
I think we are getting there, please, Ian share your final structure
with us.
The mock-up I'm working on is more about website architecture than
content. Specifically, the current Apache CMS documentation is silent on
techniques for building larger, more complex sites (without using mvn
site or Apache Forrest). The standard site template that's suggested by
the CMS documentation uses a simple compile-time server-side include
mechanism to, for example, factor out the navigation menu. This is a
good idea for keeping the navigation menu in one place, hence minimising
maintenance cost as the IA changes, but is a bad idea for managing the
complexity seen by the user for a large site.
I joined the site-dev email list at Apache, and asked questions about
this, but have so far received no response.
What I'm working on is a compromise solution that uses the navigation
SSI as suggested, should play nice with the Apache CMS wiki bookmarklet,
and uses progressive-enhancement ideas to provide a good user experience
on JavaScript enabled clients, but will also provide something workable
in non-JS environments and therefore meets accessibility guidelines.
In part the question I'm trying to answer is: can we have a convenient
three, or even four, level navigation hierarchy that plays well with the
Apache CMS. The answer to that will help us determine how flat or deep
the IA for the site can be. It's somewhat orthogonal to the current
debate on content focii.
Perhaps, there is no need for a complex and deep hierarchy.
Perhaps, the first level or global navigation is not going to change
so often and it's not a big deal to manage it manually if it's about
four or five pages only (i.e. About, Download, Getting Started,
Documentation, Getting Involved).
Perhaps, we could come up with a simple pattern and be consistent
with it to help users to find things, for example:
http://incubator.apache.org/jena/getting-started
http://incubator.apache.org/jena/documentation
http://incubator.apache.org/jena/tutorial
http://incubator.apache.org/jena/javadoc
http://incubator.apache.org/jena/arq/getting-started
http://incubator.apache.org/jena/arq/documentation
http://incubator.apache.org/jena/arq/tutorial
http://incubator.apache.org/jena/arq/javadoc
http://incubator.apache.org/jena/tdb/getting-started
http://incubator.apache.org/jena/tdb/documentation
http://incubator.apache.org/jena/tdb/tutorial
http://incubator.apache.org/jena/tdb/javadoc
http://incubator.apache.org/jena/inference/getting-started
http://incubator.apache.org/jena/inference/documentation
http://incubator.apache.org/jena/inference/tutorial
http://incubator.apache.org/jena/ontology/getting-started
http://incubator.apache.org/jena/ontology/documentation
http://incubator.apache.org/jena/ontology/tutorial
...
Where the /documentation pages have a role to briefly present what's
there and link to the other pages (no need to have a vertical or
additional navigation menu or a deep hierarchy).
/getting-started is always 1 page, 5-10 minutes.
/tutorial is 1 long page, easy to print, you are supposed to read
it from top to bottom, with a toc at the beginning.
A new section/module can be add without the need to change any
global navigation, simply add:
http://incubator.apache.org/jena/X/getting-started
http://incubator.apache.org/jena/X/documentation (if needed)
http://incubator.apache.org/jena/X/tutorial
http://incubator.apache.org/jena/X/javadoc (if needed)
... and edit the main /documentation page with a short paragraph
to point at the X section|module|component.
I found, for example, the approach and the documentation here:
http://www.openjena.org/wiki/ quite useful and well organized.
Content is short, often all in one page easy to print and read.
No need for a deep hierarchy system and a very simple navigation.
However, the problem is that the approach is not consistent and
we have multiple places/entry points for ARQ, TDB, etc.:
- http://www.openjena.org/wiki/TDB
- http://www.openjena.org/TDB/
This is somehow confusing and we should avoid it, if possible.
I find this sort of pages with too long list to chose from a
little bit confusing (i.e. too many choices in one place):
http://www.openjena.org/documentation.html
Paolo
Ian
