Mailing-List: contact jena-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: jena-dev@incubator.apache.org
Received-SPF: pass (nike.apache.org: domain of dave.e.reynolds@gmail.com
 designates 74.125.82.175 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=subject:from:to:in-reply-to:references:content-type:date:message-id
         :mime-version:x-mailer:content-transfer-encoding;
        b=phbW9JJ+nTMKJeEstJI3Ig4zbQ+2sl2pzTbmlfq32H5xI4V2np5qlJxaqahS0lP46/
         l549dgAL8iG1z5POQ1jp/RxCyWWwFlwSTg/dhWca758PbGOeaVfrsSSV6GECnawIGLBZ
         yA1sdo/bxTteulvujG4QgBoVY9t6mBebe+RC8=
Subject: Re: Jena documentation - new structure working notes
From: Dave Reynolds <dave.e.reynolds@gmail.com>
To: jena-dev@incubator.apache.org
In-Reply-To: <4D5D842A.4040605@googlemail.com>
References: <4D59C935.9070202@epimorphics.com>
	 <4D5D1C7A.6060301@googlemail.com> <4D5D2967.20803@epimorphics.com>
	 <4D5D43A4.2070008@googlemail.com> <4D5D5EC1.1000507@epimorphics.com>
	 <4D5D719B.4030604@googlemail.com> <4D5D7E96.8010507@epimorphics.com>
	 <4D5D842A.4040605@googlemail.com>
Content-Type: text/plain; charset="UTF-8"
Date: Fri, 18 Feb 2011 12:18:13 +0000
Message-ID: <1298031493.2733.58.camel@dave-desktop>
Mime-Version: 1.0
Content-Transfer-Encoding: 7bit

On Thu, 2011-02-17 at 20:25 +0000, Paolo Castagna wrote: 
> 
> Ian Dickinson wrote:
> > Hi Paolo,
> > 
> > On 17/02/11 19:06, Paolo Castagna wrote:
> >> Do you or someone else have a strong argument against having a section
> >> named "Getting Involved" | "Community" as last link in the global
> >> navigation?
> > I seem to have difficulty making this clear. There is in the proposed 
> > structure, and should remain, a section for supporting Jena developers. 
> > "Getting involved" is a perfectly fine title, and indeed is the one I 
> > used in the mock-up I was working on this afternoon.
> > 
> > So: quite the opposite of strong objection, I'm strongly in favour. As I 
> > have been since the beginning.
> > 
> > In a nutshell, all I'm objecting to is downplaying the need to make 
> > access to the documentation better for regular users, because I still 
> > think that's the dominant use case.
> 
> All fine, then.
> 
> There is a lot of existing content to migrate to the section(s) relative
> to the documentation, I continue to call them "Getting Started" and
> "Documentation", how many and how are they called in the mock-up?
> 
> This is what we saw, so far:
> 
> Homepage
>   +-- About
>   +-- Learn
>   +-- Guides
>   +-- In-Depth
>   +-- Tools
>   +-- News
>   +-- Javadoc
>   +-- Extras
>   +-- Developers
> 
> Dave suggestion was:
> 
> Homepage
>   +-- About
>   +-- Getting started
>   +-- Tutorials
>   +-- In-Depth|Documentation|Reference
>        +-- Tools
>        +-- Javadoc
>        +-- Extras
>   +-- News
>   +-- Developers

Not quite, I also proposed that there be a download section :) and
retained Ian's second level structure for the In-Depth Documentation.

> I proposed:
> 
> Homepage
>   +-- About (http://incubator.apache.org/jena/about/)
>   +-- Download ([...]/download/)
>   +-- Getting Started ([...]/getting-started/)
>   +-- Documentation ([...]/documentation/)
>   +-- Getting Involved|Community ([...]/community/)

It seems like we are only one iteration or two from agreeing on a top
level structure and substructure but please can we do this first! I see
a large number of threads which seem to be based on an assumed structure
and approach which I'm finding hard to parse.

I can't tell which of the differences between your suggestion and the
previous ones are important to you and which are accidental. 
For example are you advocating there be no News section or just happen
to have missed it off your list?

Does a consolidated suggestion like this work?

+-- About
+-- Download
       [Includes Maven]
+-- Getting started
       [Small number of short guides.]
+-- Tutorials
       [Would include topic tutorial (such as the existing RDF & SPARQL
       ones) as well as cross-cutting tutorials (such as Ian's working
       with Jena under Eclipse)]
       [I would also put the critical HOW TOs here (IO, Frames,
       Assembler) but they could be in a section under the detailed
       documentation]
+-- Documentation
    +-- javadoc
    +-- RDF
    +-- Query
    +-- TDB
    +-- SDB
    +-- Serving data (Fuseki)
    +-- Ontology
    +-- Inference
    +-- tools
    +-- extras
+-- Community
       [Should include roadmap, guidance on patch submission, links to 
       trackers etc.]
+-- News

Dave