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 14:00:29 GMT

Dave Reynolds wrote:
> On Sat, 2011-02-19 at 11:56 +0000, Paolo Castagna wrote: 
>> 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)
>> ...
> So on that sample 4 groups have it under some variant of "developer
> documentation" which was my suggestion (I suggested the label
> "Community" because you seemed to have some preference for that over
> "Developers" but it serves pretty much the same function).

My preference for what you call "Community" is "Getting Involved"
since, as I said, "it is aligned to "Getting Started" and somehow
implies an active role from the user, [which is] a thing I want to
increase" (with typos and grammatical errors fixed).

But, if you are not happy with "Getting Involved", "Community" is
fine (not my first choice, but I think it's an important section
to have and I am happy to have it, even without my preferred labeling).

Some open source projects make a distinction between "users" and
"developers" up to a point that they provide "Documentation for Users"
and "Documentation for Developers".

That distinction makes a lot of sense for those projects which provide
an application or a web app with UI that you can install and use even
if you are not a developer. Jena is more a software library with no UI,
with a few *important* exceptions: command line programs and/or
Therefore, users are more likely developers who use Jena as a library.
So, for Jena, a distinction between "Documentation for Users"
and "Documentation for Developers" makes less sense.

If I propose to split the "Documentation" into "Documentation for
Users" and "Documentation for Developers" I expect to receive strong
opposition. From our discussion emerged that some see the Jena website
(just) as a "Documentation for Users" website. Moreover, we probably
have much more content for a "Documentation for Users" section and
very little (unfortunately) content for a "Documentation for Developers"

Examples of content which I would include in a "Documentation for
Developers" are:

  - How to implement a Jena Graph SPI and put Jena on top of a different
    storage and indexing system
  - How to use/extend ARQ as a SPARQL query engine on top of a different
    RDF storage and indexing system
  - How to add new FILTER functions or property functions to ARQ
  - How to add a new indexing subsystem to TDB
  - How to plug into Jena a different/external reasoner
  - How to plug into Jena different RDF readers/writers
  - How to add a new RDBMS systems to the one supported by SDB
  - ...

But also more trivial/miscellaneous things, such as:

  - How to compile and deploy new SNAPSHOTs in your own repo
  - How to generate or apply a patch
  - How to run tests or performance tests
  - A roadmap could go here or elsewhere
  - A wish list could go here or elsewhere
  - Ideas or featured external projects using Jena in an innovative
    and interesting way could go here (or elsewhere)
  - ...

Perhaps what I call "Documentation for Developers" is what some have
called "In-Depth", but I am not so sure, since I have not seen all
the content for the "In-Depth" section yet.

So, we need to come up with a decision on how to call the: "Community"
| "Developer" | "Getting Involved" section.

My preference for the labeling is:

  - first choice: "Getting Involved"
  - second choice: "Community"
  - third choice: "Developer"

I have also sent a separate email, subject is "Jena Website » Getting
Involved", to discuss about the content to put below that section.
There are a few proposal, but I'd like to know what you and the others

Thorsten? Would you find counterintuitive to find a "Roadmap" below
a section named "Getting Involved"? I wouldn't because in order to
get involved (as developer) I need to know what's going on and the
roadmap is providing the answer to that need. Moreover, I can check
if what I am proposing as a new feature is already something which
has been planner or it's in a wish list, interesting but too far
ahead for now.

> Two groups have it under "About" which would be fine for me as an
> alternative.

My preference is for having a "Roadmap" and I am prepared to compromise
on the location. About the location, my preference is:

  - first choice: "Getting Involved" » "Roadmap"
  - second choice: "About" » "Roadmap"
  - third choice: "Documentation" » "Roadmap"

The gap between first and second is much bigger than the one between
second and third choices.

Dave, Thorsten, what do you think about renaming the "Community"
section into "Getting Involved" and put the "Roadmap" there?


> Dave

View raw message