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 12:03:08 GMT
Hi Brian,
thanks for joining the conversation. Comments inline.

Brian McBride wrote:
> 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.

Yes, good point.

How many "Getting Started" choices we want? Two? Three?

If you ask me, I would probably suggest no more than three:

  - Getting Started with Jena APIs (i.e. read/write RDF files and run
    a small SPARQL query or iterate though a few RDF statements)
  - Getting Started with TDB
  - Getting Started with Fuseki

> 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.    

I agree on the "not to treat Jena as a single monolithic" and if you look
at my messages this morning, I struggled when there was a generic page/section
such as "Download". But, I have tried to not forget there are more "things"
and recognize that.

> 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
>            supporting
>                + 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 
> Jena.
> 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.

Are you proposing to add a section in the first-level hierarchy named

   +-- About (
   +-- Download ([...]/download/)
   +-- Getting Started ([...]/getting-started/)
   +-- Documentation ([...]/documentation/)
   +-- Modules ([...]/modules/)
        +-- Jena Library (how should we call it?)
        +-- ARQ ([...]/modules/arq/) or ([...]/arq/)?
        +-- SDB
        +-- TDB
        +-- Fuseki
        +-- Joseki
   +-- Getting Involved|Community ([...]/community/)

My suggestion would be to keep "Download" and "Getting Started" and
"Documentation" as a first level and explain the difference subsystems/
modules in the textual content of the page. Since, if you are new to
Jena, you will not know what module to chose.

The "Documentation" as a first level will allow us to have a single
entry point to the documentation and construct a learning path for
the user. This page could point to specific documentation pages for
each of the modules you suggested, example:

   +-- Modules ([...]/modules/)
        +-- Jena Library (how should we call it?)
        +-- ARQ ([...]/modules/arq/) or ([...]/arq/)?
        +-- SDB
             +-- Documentation ([...]/modules/arq/documentation/) or ([...]/documentation/arq/)?
        +-- TDB
        +-- Fuseki
        +-- Joseki

Each separate module will have the opportunity to do things slightly
differently from the other modules, but consistency will help users
navigate and finding things (since while they browse they will learn
the criteria used to classify and organize things).


> Brian
> 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

View raw message