Good toolchain for writing documentation

We are going to write some documentation in our current project. It strikes me how bad the tool support for this is compared to other areas like modeling and programming. I took a tour on the web to see what had happened to all the Open Source Docbook initiatives that was promising but immature in 2000. They are still immature it seems.

The Docbook schema seems pretty solid and XML tools are availible and mature. But two areas seems still be lagging, at least in the Open Sorce world:

* User friendly Docbook editing

You shouldn’t have to learn all the 400 tags in Docbook to be productive. Not even a subset of the 50 or so most used tags. There need to be a word processor like interface. But not Word or OpenOffice since they tempt people to go outside of the schema and add style and layout. If OpenOffice could lock down the user to only be able to use a certain set of tags that would be a start. But maybe it is better to build an editor with a specific task of editing Docbook?

* Powerful and user friendly rendering engines and style sheets

Most of the Docbook generated manuals I’ve seen look pretty amateurish. Good, solid PDF, Word and XHTML generation is required. Preferably also some way to import the output into InDesign and QuarkXpress for further work.

This is my vision: you write your documentation in a structured editor, but with all the tags hidden. A writer used to Word feels instantly at home. You can move around paragraphs in a outline mode.

The tool integrates either with an IDE or has its own CVS/SVN integration (with diff functionality). The tools handles images and allows you to split big documents.

You can also use the Docbook Doclet to automatically extract API information from your Java code and have that inserted into the manual.

It’s possible to automate the generation so that your daily build could publish the latest manual with fresh API documentation on your build server.

I haven’t spend a lot of time looking at commercial offerings. Is there something like this out there?

Eclipse 3.2 unstable under Mac OS X?

I installed Eclipse 3.2 a few days ago. It’s been crashing too often to be usable for me. Is it the same for other Mac OS X (on Intel) developers?

My MacBook Pro has been upgraded to 10.4.7.