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

Reply via email to