incubator-jena-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ian Dickinson <>
Subject Jena documentation
Date Tue, 15 Feb 2011 00:29:47 GMT
First of a series of notes from my investigations around migrating the
current Jena documentation to Apache.

At the moment, we have only a basic web presence in Apache, and retain
an extensive site at (mirrored at The end-goal of migrating to Apache is that becomes the reference site, and we have
redirects in place from the other domains to the new site.

The top-level tasks that need attending to include, I think:
    * selecting an approach for developing the new site
    * designing the look & feel for the new site
    * designing the information architecture (IA) for the new
    * migrating existing content taking care of both format
      (e.g. html to markdown translation) and structure
    * putting redirects on existing URL's so that users'
      bookmarks etc do not break.

With respect to platform, the encouragement from Apache is to use the
new CMS [1], and indeed the basic site [2] that we have set up does so.
There is a However, however. Other than suggesting the use of markdown
syntax for content, providing a rather basic template, and a very basic
wiki-esque workflow using SVN, the new CMS is silent on some important
questions. Chief among these, to my mind, is dealing with complexity. We
have a lot of content, and a linear menu referencing all of our pages
isn't going to provide a good user experience and make the relevant
content easily findable. We also have automatically-generated
documentation, like javadoc, to fit in somewhere.

Some projects, such as Lucene, [3] are using Apache Forrest [4] to
generate content for the CMS, so their process is (afaict): check out
the web-site source, edit, run the Forrest generator, commit the changes
back to the source tree and the generated HTML to the CMS svn tree. That
would lose something of the wiki-like nature of the CMS. However, it
does mean that they can create a fully & flexible navigation scheme,
with sub-sections etc. There are other approaches - see separate message
for what I've found so far.

With respect to the IA, I think that the move from SF/OpenJena is a good
opportunity to revisit the structure of the Jena documentation overall,
and try to make it a bit easier for core constituencies to navigate. For
me, these are: new users, old hands and (potential) committers. Each
group has different needs. I'll make some initial suggestions in a later
message, but all ideas on this are welcome.

Assuming we stick with the Apache CMS, which uses markdown, I've had a
quick look at tools for converting HTML to markdown. There are several
around - I tried one: pandoc. Pandoc did a reasonable job, except for
tables (which aren't directly supported in markdown, though you can
embed html table syntax in markdown document). Obviously there will need
to be some manual cleanup, but the basic import looks like it should be
reasonably scriptable.

I haven't looked at the redirection issue in detail yet. Assuming we do
some restructuring of the site, which I'm in favour of, then we won't be
able to get away with a simple redirect of the TLD, if we want
individual URL's to redirect to a sensible place. However, we don't have
that many pages overall, so it shouldn't be a huge burden and once it's
done we should be able to leave it mostly alone.

Questions and comments welcome. I've joined the Apache site-dev mailing 
list, so that should hopefully be a good forum to bounce some of the 
trickier issues.


Ian Dickinson                   Epimorphics Ltd, Bristol, UK
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

View raw message