Mailing-List: contact jena-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: jena-dev@incubator.apache.org
Received-SPF: pass (athena.apache.org: domain of castagna.lists@googlemail.com
 designates 209.85.215.47 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=googlemail.com; s=gamma;
        h=message-id:date:from:user-agent:mime-version:to:subject:references
         :in-reply-to:content-type:content-transfer-encoding;
        b=pstCO8DoffAmig9RdXEgLDI8oXOAIVDzXBm4TQ9a/40gbW0Q3q48tQZsqoMW23amSz
         Wg8xJdWk3qaVeMWNJqvGMd7/zubLfmA2sFoHgS1PE1w0HDLIQpC25xtrk0Zq32ejU9ba
         XNj2Xb8MR5jWRYKyQF9I5cpXE+cWdjbZDZU0Y=
Message-ID: <4D5D5048.4010200@googlemail.com>
Date: Thu, 17 Feb 2011 16:43:52 +0000
From: Paolo Castagna <castagna.lists@googlemail.com>
User-Agent: Thunderbird 2.0.0.24 (X11/20101027)
MIME-Version: 1.0
To: jena-dev@incubator.apache.org
Subject: Re: Jena documentation - new structure working notes
References: <4D59C935.9070202@epimorphics.com>
In-Reply-To: <4D59C935.9070202@epimorphics.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit


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 (http://incubator.apache.org/jena/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.

Let's check it 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
>