incubator-jena-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ian Dickinson <>
Subject Re: more on documentation structure
Date Thu, 17 Feb 2011 00:22:34 GMT
Hi Brian,
Thanks for your comments.

On 16/02/11 16:50, Brian McBride wrote:
> One comment on goals, born out of recent frustrations, is that there is
> a class of potential Jena user who building some app or whatever, who
> needs a component to perform some specific subtask. Lets call her
> Joanna. Joanna is an experienced programmer, is busy, has a deadline
> looming and is looking to make a quick decision about a component to use
> for some RDF processing in her application. Her application isn't
> 'about' RDF - its not a major thing - its just that she has to do some
> RDF processing in order to get her job done. Maybe she has a DOM and
> just wants to process it to extract RDF from the embedded RDFa and then
> munge it. She doesn't want a tutorial on RDF or anything like that and
> she doesn't want to plow through a lot of javadoc to figure out if Jena
> will do what she wants. On another day in another project she is looking
> for a triple store, she has some basic requirements (fast read, standard
> update protocol, SPARQL 1.1) - and she want a quick way of determining
> if TDB, SDB, Fuseki etc meet those requirements.
> Joanna needs to a quick way to figure which component she should be
> looking at, whether that will do the job, and then a pointer to where to
> look to figure out how. In my mind she is looking for some data sheets
> about the components - just the bare facts ma'am type documents.
> Reading your mind maps, I don't think Joanna is represented there,
I disagree. Well, at least it was very much my intention to include a 
Joanna-like persona. I may well be guilty of a sin of unclarity, but 
not, I hope, of omission :)

Specifically, the constituency "old hands" would be better as 
"experienced programmer", with an assumption that some familiarity with 
RDF is assumed. I think this is implicit in your persona as well: if 
Joanna doesn't know anything about RDF at all, she isn't going to be 
able to make an informed choice that she even needs Jena-like 
functionality in her solution design.

Given that, the task-based topic indexes are the key thing. Personally, 
I think this is one of the weak links in the current Jena documentation. 
It's also one that I'm personally keen to write some new content to 
address. I believe that it's primarily about indexing: putting routes in 
to the existing material into language that the reader - Joanna - can 
related to their current design or development tasks. A pattern library 
may be part of it too, though that probably fails the "don't be too 
ambitious" test for the first iteration!

> but
> maybe I'm missing something, or maybe she isn't important enough to show
> up.


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