more on documentation structure

[Brian McBride <br...@epimorphics.com>]

Hi Ian,

I found the messages about documentation structure in the archive, but 
haven't figured out how to reply to messages from the Archive, so sorry 
for the new thread.

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, but 
maybe I'm missing something, or maybe she isn't important enough to show 
up.

Brian

Re: more on documentation structure

[Brian McBride <br...@epimorphics.com>]

Hi Ian,

On 17/02/2011 00:22, Ian Dickinson wrote:
[...]
>>
>> 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",
Yes.  I read "olds hands" as "old Jena hands"

[...]
>
> Given that, the task-based topic indexes are the key thing. 
I think the datasheets are key to Joanna - but they might be there too.

Brian

Re: more on documentation structure

[Ian Dickinson <ia...@epimorphics.com>]

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


-- 
____________________________________________________________
Ian Dickinson                   Epimorphics Ltd, Bristol, UK
mailto:ian@epimorphics.com        http://www.epimorphics.com
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