Mailing-List: contact jena-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: jena-dev@incubator.apache.org
Received-SPF: pass (nike.apache.org: domain of castagna.lists@googlemail.com
 designates 209.85.213.175 as permitted sender)
Message-ID: <4EBD32F6.1000306@googlemail.com>
Date: Fri, 11 Nov 2011 06:36:38 -0800
From: Paolo Castagna <castagna.lists@googlemail.com>
User-Agent: Thunderbird 2.0.0.24 (X11/20101027)
MIME-Version: 1.0
To: jena-dev@incubator.apache.org
Subject: Re: Versioned/Historical Documentation (was RE: How to decide to
 release ...)
References: <005b01cca07c$a76a6b60$f63f4220$@apache.org>
In-Reply-To: <005b01cca07c$a76a6b60$f63f4220$@apache.org>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit

Hi Dennis,
you are right, but doing what you suggest also adds a lot of overhead.
Some projects just maintain the documentation for the latest stable release.
Apache Jena is not as big as Openoffice fortunately!

We have the website in SVN and we are using the Apache CMS (kudos to Ian), here:
http://svn.apache.org/repos/asf/incubator/jena/site/
... so we can tag the documentation as well as the code when we do a release
if we want to and if we decide this is an useful thing to do.

Unfortunately, it's not actually the HTML website or something you can checkout
and browse. The syntax is Markdown.

But, perhaps you or someone else could provide a little script to checkout the
site/ and build it locally.

My curiosity, are you using Apache Jena and/or planning to use it in the near
future?

Are you involved in OpenOffice and/or the Apache ODF Toolkit?

Do you know if there is anything interesting going on there in relation to
RDF we should be aware of?

Looking at Apache ODF Toolkit and how it relates to RDF (and Apache Jena) and/or
Apache Tika and/or Apache Any23 and/or Apache Nutch is on my (too long) todo
list.

Paolo

  [1] http://incubator.apache.org/odftoolkit/


Dennis E. Hamilton wrote:
> As there becomes a history of releases, it becomes important to also retain 
> the documentation that applied at that time.
> 
> That's especially applicable as APIs change in any way, new modules and 
> modularizations are introduced, etc.  For example, unless the JavaDoc reflects 
> versions, it is likely to be current as of some build or trunk snapshot or 
> whatever ... (maybe not even on exactly the same cycle as releases).
> 
> I don't know of a perfect way to synchronize documentation, but it probably 
> means that documentation is version-controlled to some degree, somehow.  At 
> Apache, that usually means in the SVN (even if the documentation itself is 
> produced from some sort of authoring source by an SVN-downstream process).
> 
> So it becomes a release artifact.
> 
> I am thinking of technical documentation with details that can vary from 
> release to release.  Other kinds of documentation have their own release 
> cycles and staging and might be kept outside of release cycles, including 
> community-maintained materials on a wiki, etc.
> 
> Side Note: The experience in the OpenOffice.org podling is that it is wise to 
> get the IP right on wiki and downloadable contributions in case some of it is 
> important to tie to releases and be cherry-picked into release artifacts.  The 
> ASF preference appears to be to use ALv2 for project-produced documentation 
> and also do the usual IP/3rd-party magic on documentation from elsewhere.
> 
> -----Original Message-----
> From: Paolo Castagna [mailto:castagna.lists@googlemail.com]
> Sent: Friday, November 11, 2011 05:17
> To: jena-dev@incubator.apache.org
> Subject: Re: How to decide to release (was: Re: JIRA issues and "Fix 
> Version/s"...)
> 
> Andy Seaborne wrote:
>>   JENA-110
>>   Decide on doc/ (/me don't put in the downloads)
> 
> +1 on removing doc/ entirely
> 
> The official documentation is on the website.
> 
> Paolo