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 Sat, 19 Feb 2011 11:56:56 GMT
Hi Thorsten,
thank you for your reply.

Thorsten Möller wrote:
> Hi,
> I've silently followed the discussion in this thread and I'd like to 
> comment on the structure.
> On Friday, February 18, 2011 1:37 PM [GMT+1=CET],
> Paolo Castagna <> wrote (with possible 
> deletions):
>>> 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.]
> Putting Roadmap below Community is counterintuitive, at best. 

I have done a few check with some other websites, a few examples:

About Subversion » Roadmap

Documentation For Developers » Miscellaneous » Roadmap - outdated ;-)
(it's in a wiki, reachable via a contextual link).

Developers » RoadMap (contextual/navigational link in a wiki)

About » Roadmap ->

Roadmap (first level link it the global navigation) ->

Developer Documentation » Roadmap ->
(contextual/navigational link from the wiki homepage)

Developer Documentation » Roadmap -> ->
(contextual/navigational link from the wiki homepage)


You are probably right, if it is counterintuitive and confusing for
you it is probably confusing for others.

And, you are right, the "Roadmap" I meant is about Jena as software
project, not the "Community" or not about how to people can become
more active "Getting Involved" with the Jena project.

However, I fear "opposition" proposing the "Roadmap" as a top level
item in the global navigation, simply because Jena has never had a
written down roadmap on the website, people are reluctant to write
new content (since we are all busy) and some might not even like to
have an explicity roadmap (even without dates in it, even without
promises or any guarantee that something will get done by the next

However, I think the "Roadmap" is an important (and missing) piece
for people using Jena or people willing to better understand what's
going on (from a point of view of development) and what's the
direction/evolution of the project.

If people don't like to have the "Roadmap" as top-level item in the
global navigation, where would you suggest to put it?

  1. "About" » "Roadmap" ?
  2. "Documentation" » "Roadmap" ?
  3. ...

If you have noticed, "Documentation" in the context of the Jena
project is more "Documentation" for users, not for developers.
Where users == developers who use Jena while developers ==
developers who use Jena, but look at the sources, they can find
a bug and post a patch for it on JIRA and, maybe in the future,
they could become committers.

Documentation for developers is clearly not the biggest priority.

The "Roadmap" is a small piece of documentation which is targeted
at developers or a project managers who are leading software projects
in a commercial environment and what to know where Jena is heading.
I say so, just to add another and different reason why a "Roadmap"
might be good for the Jena website (and it's not for developers). ;-)

> To most of 
> us it seems clear what a roadmap is about - functions that have been 
> identified and are planned to be implemented in the future. However, in 
> this case some may think "Is this a roadmap about the community?" - 
> certainly not. 

About "to be implemented in the future" I see a difference between a
roadmap (i.e. near future == next release or so) and a wish list
(i.e. longer term future == next year or so).

I see a roadmap as something we have already started working on it or
we are going to start working on it very soon.

I see a wish list as something we would love to do (if only someone
capable could help us) but we have no time to do or we have not
though enough about it or we do not know exactly how to do it and
some time and experiments will be needed to find out exactly what we
can do.

I'd like the Jena project to have both: a roadmap and a wish list
on the website somewhere. Because I believe this are one of the
many things we can do to better interact with the community of
developers who are using Jena (and, maybe, in the future could help
us, not only reporting bugs but also running tests, writing patches
and coming up with new ideas to improve the software or new ideas
for new and useful functionalities).

A roadmap and a wish list should not be long, 1 page to start with.

The risk is similar to a "News" page, it requires some commitment,
but, if you ask me, it's something we should do.

 > In my opinion, a roadmap is of top-level interest
> (provided that it exists).

I agree.

Do you think of a good reason why Jena should not have a roadmap?

 > Actually, I often see myself searching for a
> roadmap when visiting Web sites of projects that I use regularly (and 
> often it does not exist).

I search for it as well, in particular when I "depend" on an open
source software project and I want to better understand the direction
which is going (if there is any direction at all).

There can be many reasons why a roadmap is not there, starting from:
there is no roadmap/direction, people prefer to spend time writing
code and fixing bugs rather than updating the roadmap page on a web
site, people think a roadmap is useless, etc.

Finally, a few website point for their roadmap at JIRA. Personally,
I find that somehow confusing (and more confusing with the new
version of JIRA... I was more comfortable with the old "roadmap"
tab in the old JIRA).

What I propose is one roadmap page on the Jena website, short,
a few paragraphs to explain what we are doing and why and if there
are JIRA issues we should link to those.

Jena JIRA has no "roadmap"... you can see what's going on, but is not
immediate or organized with an order and an explanation of why there
are those open issues, the rationale behind decisions has not been
made explicit.

You can check "Popular Issues" here:
... we can debate on the meaning of "popular", but again this can be
an indirect feedback for us all and the more we listen to concerns
and problem of people using Jena (for business as well) the better,

As soon as we agree on:

  - do we want/need a roadmap?
  - where do we put it in the website navigation?

I'll send a message about the content (which is the most important
thing at the end).

Thank you again Thorsten and, please, continue feedback to us,

> A good example in this regard is SVN [1].
> Regards,
> Thorsten
> [1]
>>> +-- News

View raw message