incubator-jena-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Reynolds <>
Subject Re: Jena documentation - new structure working notes
Date Tue, 15 Feb 2011 10:57:10 GMT
On Tue, 2011-02-15 at 00:30 +0000, Ian Dickinson wrote:

[Great job summarizing the current structure and possible goals!]

> The final attachment sketches a possible solution. The first level of 
> the hierarchy roughly corresponds to groups of suggested user goals. 

I think there's a missing top level goal in there, "get Jena" :) 
(should include the license link as well as download and maven).

The difference between learn/guide/indepth isn't completely clear to me,
suggest relabelling to something like:
  - Getting started
  - Tutorials
  - In Depth (or Documentation or Reference)

> However, three of the goals are 
> sufficiently large that having a second level of hierarchy would be 
> helpful to our users, I think. I propose that, where it's necessary, the 
> second level of hierarchy would ideally be consistent, to aide 
> findability. 

Not sure about that, I think the structure of those tasks is different.
In particular, the learn/Tutorials can be cross-cutting things (setting
up under eclipse, building a complete application etc) and don't
necessarily follow the component structure of Jena.

We don't want to end up with a problem of "now do I find this under
learn or guide or in depth?"

My inclination would be to keep the Getting Started and Tutorials
sections fairly simple. I'm not sure we are going to have so many
tutorials that a lot of structure is needed there :)

I agree we want a clear structure for the In Depth section. 

> A working suggestion is:
> RDF (i.e. the core API)
> querying (ARQ & SPARQL)
> persistence (TDB, SDB, FileModel, etc)
> ontology API
> inference
> serving data (Joseki, Fuseki)

I suggested flattening out a little to bring the components like TDB and
SDB up to to top level, use choice of titles to make their role clear.

I wonder if some or all of "extras", "tools" and "javadoc" could go in
the In Depth section rather than top level?

> My proposal is that we use a static navigation structure, using nested 
> <ul> elements to model the hierarchy, but use progressive enhancement 
> javascript techniques to pretty this up as a more dynamic 
> reveal-on-demand menu structure.  That way, we get benefits of 
> accessibility, and visibility to search engines, keep the ease-of-update 
> of the Apache CMS (thus avoiding the Forrest approach of update the site 
> config & rebuild everything), but manage the visual and complexity we 
> present to most users on capable browsers. 



View raw message