incubator-jena-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paolo Castagna <>
Subject Re: Jena documentation - new structure working notes
Date Fri, 18 Feb 2011 00:36:28 GMT

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:


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: (if needed) (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: 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.:


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):


> Ian

View raw message