I'd be interested in hearing your views. As an aside could the class documentation not be generated directly from the source using something like Doxygen?
I personally don't like docs produced using Doxygen (or similar). They still require considerable effort and in most cases look like reference rather than users guide/tutorial.
Being in the thick of documentation right now, I think it would be a great SOC project to try to extend/adapt Doxygen to ameliorate these issues while preserving it's nice aspects. It would also be great to extend it so that code snippets can be directly inserted by name into the documentation (sort of like Knuth's WEB system in reverse) so that the code and dox stay in sync (this is one of the todos on the Doxygen web site already). That said, I like a lot of the aspects of Doxygen - better control over sectioning and pages and extended syntax for mainpage.h would be a great extension. Matthias