incubator-jena-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paolo Castagna <>
Subject Re: Jena documentation - new structure working notes
Date Thu, 17 Feb 2011 15:49:56 GMT
Hi Ian.

Ian Dickinson wrote:
> Hi Paolo,
> On 17/02/11 13:02, Paolo Castagna wrote:
>> The fact that we need a website and documentation is obvious and
>> it's given for granted.
>> But, "why" do we want a website?
>> The aim has not been clearly stated, so far.
>> If you ask me and in the context of an Apache project, the overall
>> aim of a Jena website is to have as much (happy) people as possible
>> using Jena (i.e. increasing user base and supporting current users).
> +1
>> We should aim at quickly move them from new users to expert as quick
>> as possible and with a self-service process as possible.
> +1
>> Finally, the ultimate goal is to transform expert users from users
>> to developers, contributors and, maybe, (smart) committers.
> I disagree that this is the ultimate goal. Certainly we do want to grow
> the community of Jena contributors and committers - this was a key
> motivation for entering Apache. But in a steady state, I would expect
> Jena to have multiple thousands of users, but tens or maybe at a pinch
> hundreds of committers. So while serving the needs of Jena developers
> and committers is important, indeed very important , it's not, to me,
> the ultimate goal.

I agree with the fact that there will be differences between number
of users/developers, expert users/developers, contributors and finally
committers, order of magnitudes difference.

However, I don't see that as a good reason not to aim at moving people
from being users to expert users/developers and, if possible, up to a
point where they can help us developing new features, fixing bugs,
submitting patches, improving performances, etc. and, overall,
achieving more that what we can do (since we are a small number of
very busy people with little bandwidth and limits).

Also, now that I am thinking more about Jena users and developers...
... what's the difference between a Jena user and a Jena developer?
I mean, Jena users are always developers, but they don't look at the
Jena source code, they don't compile Jena, they simply use it as a

Jena developers are different, they look at the source, they can
find a bug and/or produce a patch for it, etc.

Is this something important to keep in mind when we think about the
content of the website?

I would probably tend to say that, so far, the documentation has been
too focused on the Jena users and too little on the Jena developers.

We can probably do something more/better to move users, from being
users to be developers. This could also have the side effect of
reducing support load for new users (since you have more developers
who can do that if they want to) and new users might remain less
time users.

>> In less words, the website should be tuned at growing a community
>> around Jena. Therefore, in my opinion, we need to think about those
>> steps and movements and make it as easy as possible for everybody
>> who might be interested.
> Certainly these aims should be included. My advocacy is actually that
> the *primary* aim of the documentation is to help users make effective
> use of the toolkit. One measure of success, for me, would be that the
> growth of the support load on jena-users is slower than the growth in
> the number of downloads.

Is the *primary* aim of the documentation == the *primary* aim of the
Jena website?

If so, would it be correct to think that a website which only support
Jena users is enough? For me, clearly, this would not be enough. ;-)

I am not sure I fully agree on the success metric as well. Number of
downloads or decrease in the support load are not good enough for me.
You can reduce your support cost to zero if you want. Can't you?
We can increase number of downloads in many ways, having a huge number
of newbies users who download Jena and simply gave up (with no support
cost) will increase the number of downloads.

Personally, I would prefer to look at number of bugs found by others
(not Jena committers) or number of feature requests from others or
number of patches or, why not?, doubling number of committers in
one or two years. I am not saying, these should absolutely be the
measure of success, but these seems to me more appealing (and ambitious)
rather than downloads or support load on jena-users mailing list.

>> How are we going to transform new users into expert users?
> I proposed several goals for the site around the theme of learning Jena,
> for both new users (getting started, tutorials) and more experienced
> users (task-based documentation, reference material)
>> How are we going to transform expert users into developers/contributors?
> There should definitely be a developers/committers section, I agree.


This is what others call: getting involved|community section in their
website. I'll think more about this part of the website and come back
with ideas and proposals on a separate thread.

> However, beyond the process questions (how to submit a patch) and
> detailed reference materials (above), it's hard to know what else could
> be done to bring about the transformation you describe. In fact, I don't
> know what *I* would want in such a section on another OS project I was
> interested in.

A roadmap can help. If someone, maybe a bright student with a lot of free
time in his/her hands, want to help with something, he/she should be able
to have a sense of direction and what's the work in progress. JIRA is a
good place to check for this... and perhaps the roadmap could live there.
Or, we could have 5 to 10 issues summarized and described in a roadmap
on the website.

An (old) example (not perfect, but better than nothing):


Another example:


A wish list could help. In the wish list we put things it would be nice
to have, but we are not actively working on it. But, if someone really
keen comes along, it could find some starting point and maybe guidance/

An example:


Or another:


However, it takes some effort to keep those pages updated over a long
period of time. So, perhaps, we can use JIRA for that and have just
one short page with 5 to 10 JIRA issues summarized and link to them.

Another thing we could/can do is to give others the opportunity to write
two/three paragraphs to describe some innovative (and open source) project
they have done using Jena.

Internships, Google Summer Of Code, or other similar activities should
also be part of a list of possibilities to engage more with developers
who might help us more and more (up to a point where they become committers).

These are just a few examples/ideas, on the top of my head, while I am
writing this email. I am sure other might have other good ideas/suggestions.

>> So, why do we want a website?
> Hopefully, I've made my answer clear above. Happy for anyone else to
> chime in :)


To me, "helping users make effective use of the toolkit" is very important,
but somehow 'limiting' and, hopefully, I explained why: it focuses on users
only and not on their evolution, grow and engagement with the Jena community.

However, there is no point to have long debates on this. So long we have
a section "Getting Involved" or "Community" as main section on the new
website, I am happy and I'll do my best to contribute ideas and content
for that (as well as the other part of the website I can help with).

Not being an English native speaker I appreciate any help in reviewing and
transforming my Inglish in proper English. :-)

Thanks Ian, again.


> Ian

View raw message