Jena Website » Documentation

[Paolo Castagna <ca...@googlemail.com>]

Assuming a first level structure like this:

Homepage
  +-- About (http://incubator.apache.org/jena/about/)
  +-- Download ([...]/download/)
  +-- Getting Started ([...]/getting-started/)
  +-- Documentation ([...]/documentation/)
  +-- Getting Involved|Community ([...]/community/)

Assuming that "Documentation" is one of the first level section.

This message is about a proposal to reorganize the content relative
to what we call "Documentation". Most of the content is available
and linked here: http://www.openjena.org/documentation.html

I am not proposing to rewrite the content.

However, my proposal involve writing a few paragraphs to help
the reader deciding where to go to satisfy his/her needs or to
guide him though the whole documentation with a coherent and
gradual learning path.

Proposed content for the "Documentation" page.

This is the entry page to the documentation for users who are
already familiar with the "Getting Started" and have already
downloaded Jena.

  +-- Documentation ([...]/documentation/)

Jena Documentation

1 paragraph introduction to recommend, if you have not done already,
to read the "Getting Started" section first and the Jena or ARQ tutorial
as second step.

The rest of the documentation could be organized in these sections:

  - Jena API and I/O
  - Querying with SPARQL
  - Storage
  - Ontology API
  - Inference
  - More

Each section should describe in 1 or 2 short paragraphs the scope of
the section, what the reader will learn going further on that section,
possibly, using keyword with link to the material. A "more" link,
if necessary, could move the reader to a more detailed list (but,
I think we can avoid this).

As an example and reusing as much as the content available, the
"Storage" section could be:

  "Jena can manipulate RDF data using in-memory datastructure,
   however in order to persist data two storage systems are
   available: SDB which uses a relational database and TDB
   which uses a native persistece engine with custom indexing
   and storage. SDB has full ACID transactions support and [this]
   while TDB is faster and simpler. In you do not need [this]
   and [that] start with TDB.
   SDB and TDB can be downloaded [link to the "Download" page,
   subsection about SDB and TDB] as separate systems.
   The original RDB system is still shipped with Jena for legacy
   applications. It is deprecated for new development."

   SDB and TDB words would link to:

    - http://incubator.apache.org/jena/sdb/
    - http://incubator.apache.org/jena/tdb/
    - http://incubator.apache.org/jena/rdb/ (deprecated)

   Those pages are the entry point for people interested in SDB
   or TDB.

   Or, if you prefer, links could go to:

    - http://incubator.apache.org/jena/documentation/sdb/
    - http://incubator.apache.org/jena/documentation/tdb/
    - http://incubator.apache.org/jena/documentation/rdb/ (deprecated)

This way the "Documentation" page would be more readable and
it should help the reader to decide where to go, rather than
providing just a long list of links.

In total, it's 5 or 6 short sections.

The "More" section should point to the "FAQ" we could have just
one page, with clear TOC at the beginning and if necessary group
questions by topic, including SPARQL, ARQ, TDB, SDB which are
separate now.

The "Documentation" section is the largest, the most problematic
and the one we have most of the content already available.

Paolo