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 [effort].
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 [mailto:[email protected]] Sent: Friday, November 11, 2011 06:37 To: [email protected] 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), 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. [ ... ] 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:[email protected]] > Sent: Friday, November 11, 2011 05:17 > To: [email protected] > 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
smime.p7s
Description: S/MIME cryptographic signature
