incubator-jena-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Dennis E. Hamilton" <>
Subject RE: Versioned/Historical Documentation (was RE: How to decide to release ...)
Date Fri, 11 Nov 2011 15:39:07 GMT
I would have thought it easier to synchronize release-varying documentation on 
a small project, but I suppose that depends on the nature of the documentation 

Yes, I understand about repos/.../project-name/site/ and the use of markdown. 
It had not occurred to me that capturing a snapshot of the site would be 
effective for incorporation in a distro.  I just hadn't connected the dots.

If there is web documentation pertinent to a release, or that should be 
captured with a release, static pages are appropriate, much the way JavaDoc 
pages are static.

This may be an use case that just doesn't work well with CMS-based site 
generation.  Interesting.

 - Dennis

-----Original Message-----
From: Paolo Castagna []
Sent: Friday, November 11, 2011 06:37
Subject: Re: Versioned/Historical Documentation (was RE: How to decide to 
release ...)

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), 
... 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.

[ ... ]

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 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 []
> Sent: Friday, November 11, 2011 05:17
> To:
> 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

View raw message