I spent time on the documentation in three ways: 1. Updating the links from 0.95 to 1.0 and from 0.94 to 0.95. This can be avoided if we call the directories 'latest' and 'previous'.
2. Updating the compliance page. I did this with emacs regexes, but they are tricky. I think the setup of the page needs to be changed to make it scriptable. 3. Updating the documentation. Some documentation is well maintained between releases, other documentation is left to become outdated. This will always be a problem. In this release I am trying to make a slight paradigm shift: Forget about 0.20.x, it is too far in the past (but Pascal just wrote that there are still questions about it). Such changes will always occur and take time. I would call it pre-release work rather than part of the release build. I cannot see if Docbook documents would be easier to maintain. It would certainly get them out of the web site structure, which may encourage people to modify them without fear to get tangled in structural problems. An effort to script the release build, including modifying the documentation automatically as much as possible, will reveal how difficult and time consuming a release really is, apart from pre-release work like updating the README, news, and taking a good look at other documents. Simon On Tue, Jul 06, 2010 at 10:08:13PM +0200, Jeremias Maerki wrote: > Hi Vincent, > > I was actually thinking of converting only the product docs, not the > website. For just HTML output, I find Forrest quite nice, but the > linking for the various versions creates a lot of overhead for a release. > And that's basically what triggered that thought. > > Basically, I'd suggest to do this: > - Basic website with Forrest with links to versioned product docs and > Javadoc. > - Product docs converted to DocBook, offering HTML and PDF versions > similar to the SVN Book. Including FAQ. > - Move developer docs entirely to the Wiki where it is more likely to be > maintained. Developer docs in two places is a bad idea. > > One problem remains for which I don't have a good answer: the compliance > page which is a bit hard to maintain. -- Simon Pepping home page: http://www.leverkruid.eu
