incubator-jena-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ian Dickinson <>
Subject Re: Jena documentation - new structure working notes
Date Tue, 15 Feb 2011 11:18:47 GMT
Hi Dave,
Thanks for your comments.

On 15/02/11 10:57, Dave Reynolds wrote:
> On Tue, 2011-02-15 at 00:30 +0000, Ian Dickinson wrote:
> [Great job summarizing the current structure and possible goals!]
>> The final attachment sketches a possible solution. The first level of 
>> the hierarchy roughly corresponds to groups of suggested user goals. 
> I think there's a missing top level goal in there, "get Jena" :) 
> (should include the license link as well as download and maven).
That one is in there already - fifth from the bottom.

> The difference between learn/guide/indepth isn't completely clear to me,
> suggest relabelling to something like:
>   - Getting started
>   - Tutorials
>   - In Depth (or Documentation or Reference)
I agree it's not completely clear yet, even to me. However, I have an
intuition there's an entry route we don't have clearly at the moment,
which is somewhere between getting started (which should be very clear
and simple) and the full reference material (for which completeness is
the main goal), but which takes a different approach to follow-along
tutorials. It's a bit vague in my head, but I think it's something
analogous to a progressive reveal UI pattern: it helps to have a level
of detail that gives a good overview of the territory - what you can do
with Jena - without too deep a dive into details.

I know for myself I'm often frustrated with other tools/libraries that
there's a big gap between following the tutorials and sipping from the
firehose. I also think that we already have some Jena content that fits
in this intermediate category.

>> 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. 
> Not sure about that, I think the structure of those tasks is different.
> In particular, the learn/Tutorials can be cross-cutting things (setting
> up under eclipse, building a complete application etc) and don't
> necessarily follow the component structure of Jena.
Good point.

> We don't want to end up with a problem of "now do I find this under
> learn or guide or in depth?"
That's fair. Any document hierarchy is going to have that problem to
some degree - I was envisaging that we'd put cross-cutting links from
one section to other sections, to mitigate that to some degree.

> My inclination would be to keep the Getting Started and Tutorials
> sections fairly simple. I'm not sure we are going to have so many
> tutorials that a lot of structure is needed there :)

> I agree we want a clear structure for the In Depth section. 
>> 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)
> I suggested flattening out a little to bring the components like TDB and
> SDB up to to top level, use choice of titles to make their role clear.

> I wonder if some or all of "extras", "tools" and "javadoc" could go in
> the In Depth section rather than top level?
Certainly something to try.


Ian Dickinson                   Epimorphics Ltd, Bristol, UK
cell: +44-7786-850536              landline: +44-1275-399069
Epimorphics Ltd.  is a limited company registered in England
(no. 7016688). Registered address: Court Lodge, 105 High St,
              Portishead, Bristol BS20 6PT, UK

View raw message