incubator-jena-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Brian McBride <>
Subject Re: Jena documentation - new structure working notes
Date Fri, 18 Feb 2011 11:08:12 GMT
There has been some good discussion in this thread and I agree with 
Paolo that it would be suboptimal to present the user with a long list 
of choices e.g. in a getting started page.  However, short lists don't 
have to be length 1.

I suggest it might be better not to treat Jena as a single monolothic 
thing, but to give the user a map to its regions at the top level.    
One way to do this might be to have a  top level page with a menu on the 
left and the main body of the text that says something along the lines of:

    * Jena is a software package consisting of a number of modules:
          o a Java library for creating and manipulating RDF graphs
                + reading/writing different text formats for RDF graphs
                + creating/editing/querying RDF graphs
                + creating/editing/querying OWL ontologies
                + rule based inference on RDF and graphs and OWL ontologies
          o TDB: a file system based persistent store for RDF graphs
            optimised for speed of query and access supporting:
                + SPARQL 1.1
                + integration with Lucene for text search
                + named graphs
                + fast bulk loading from common RDF serialistion formats
          o Fuseki: an RDF server that runs out of the box stand alone
            or in an app server supporting:
                + SPARQL protocol 1.1
                + ...

I won't have expressed this list as others would prefer to express it.  
The above is illustrative and can no doubt be expressed better.  For 
example, one might want to bring the OWL support and inference out as a 
top level module.

The left hand menu items at this level will point to generic material, 
e.g. the getting started will be designed for someone completely new to 

There will also be subpages for each of the modules, e.g. the API, the 
TDB, Fuseki etc.  The getting started menu items on those subpages would 
refer to material specific to that module.

The left hand menu structure would contain a modules section to aid 
navigation to the submodules pages.


On 17/02/2011 16:48, Paolo Castagna wrote:
> Ian Dickinson wrote:
>> Thinking about the structure of the new site, I spent some time 
>> surveying what we have. The attached pdf & freemind documents show 
>> the current structure, including tdb, sdb and fuseki.  The second 
>> attachment shows some suggested goals for the new IA, thinking in 
>> terms of the user goals we would like to satisfy.
>> The final attachment sketches a possible solution. 
> I propose to go from this:
> Homepage
>  +-- About
>  +-- Learn
>  +-- Guides
>  +-- In-Depth
>  +-- Tools
>  +-- News
>  +-- Javadoc
>  +-- Extras
>  +-- Developers
> To this:
> Homepage
>  +-- About (
>  +-- Download ([...]/download/)
>  +-- Getting Started ([...]/getting-started/)
>  +-- Documentation ([...]/documentation/)
>  +-- Getting Involved|Community ([...]/community/)
> ... and I am not even sure we need "Download".
> However, if we want to increase number of downloads, I propose to keep it
> there, in the global navigation after "About". Otherwise, it will be the
> first paragraph in "Getting Started". However, this would not serve well
> expert users/developers who just want to get the latest Jena release.
> The easy "Learn" is covered by "Getting Started", more "Learn" is covered
> by "Documentation". "In-Depth" is covered by "Documentation". "Javadoc"
> is a link below "Documentation" (i.e. /documentation/javadoc/).
> "Extras" and "Developers" are below "Getting Involved"|"Community".
> "News" could be in the homepage and/or a blog linked from the homepage
> or "Community".
> Let's check the first level structure with the goals:
>  - explain what Jena is -> About
>  - how to learn Jena -> Getting Started + Documentation
>  - How do I? -> Documentation
>  - Delve into technology -> Documentation
>  - Get Jena -> Download
>  - Drive Jena using command line utilities -> Documentation
>  - Going beyond Jena -> Getting Involved | Community
>  - See what has been happening recently -> Homepage | Community
>  - Process goal -> less clear choices
> Once we agree on the first level structure we can start discussing and
> producing content for it: 6 pages to start with (homepage + 5 sections).
>> The first level of the hierarchy roughly corresponds to groups of 
>> suggested user goals. These could be presented as a horizontal tab 
>> array.
> +1
> Either horizontal or vertical, but a global navigation always present
> and consistent whenever you are in the website.
>> The second level of hierarchy would in most cases be actual topic 
>> documents (such as the eyeball howto in the tools section). 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. 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)
>> 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. 
> +1
> Initially, a static navigation structure is sufficient for the global
> navigation.
> > 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. 
>> This would all need some prototyping and experimentation, of course.
>> Comments welcome.
>> Ian

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message