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.43 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=rKGmt1JNS+gvwslMUGyZ64mIjS78dIe5xmN6MJkSQBQgHs3x+clk3Zd+KzoqxK1zcA
         1awCq7j5e7WTxkSrh9CQgrXmqLXTBJOtrJpK2j8qnHFX4HVXr0bLd8wtMAd0hOfPKKEp
         uLsbvBYRtSydqffcmiyhQ3FCdPLVERJsfU7FY=
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: <4D5E6813.3080303@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> <1298031493.2733.58.camel@dave-desktop>
	 <4D5E6813.3080303@googlemail.com>
Content-Type: text/plain; charset="UTF-8"
Date: Fri, 18 Feb 2011 13:06:22 +0000
Message-ID: <1298034382.2733.73.camel@dave-desktop>
Mime-Version: 1.0
Content-Transfer-Encoding: 7bit

On Fri, 2011-02-18 at 12:37 +0000, Paolo Castagna wrote: 
> 
> Dave Reynolds wrote:

> > 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
> 
> I can be happy with that.

Great. 

> As a user landing on a project which gives me the choice between "Tutorials"
> and "Documentation" I would probably ask myself "why "Tutorials" are not
> below "Documentation""? But, it's not a big problem.

Happy to pick a better title (we previously suggested In Depth). 

Having found myself as a beginner tying to use various (Ruby) libraries
this last two weeks I've found separate Tutorials sections to be useful
and quite common.  Typically the getting started is enough to install
and do hello world but not enough to understand what's going on.
Documentation is often, like ours, dominated by API level documentation
and details that assume you have the overall picture in your head, it is
easy to get lost in until have a start at understanding the tool.
Tutorials bridge that gap.

> I am not sure what you intend to put in Documentation/RDF.

I was following Ian's suggested naming, basically the core API. Our main
material at the level at the moment is the RDF Tutorial and some HOW TOs
so depending on how we treat the HOW TOs it may be ... thin ... to begin
with :)

> I am happy the "Community" page is there, but my preferred labeling would
> be "Getting Involved" since it is aligned to "Getting Started" and somehow
> imply an active role from the user, a think I want to increase.

Fine by me. I've seen both used reasonably equally.

> I have already commented about News. But, I have no strong opposition to it.

Happy to go along with you an Andy on that. A news section must be
active and up to date otherwise it is a negative. Better to have no
section rather than something poor.

Dave