I came to Haiku after the discussion about docbook versus doxygen, at least I don't remember it... :-) In many places in the code, I came across doxygen documentation, and I thought it was pretty nice. Whenever it made sense, I updated documentation, or tried to include documentation when I added new functions. I guess this is exactly the point of doxygen. I have no idea what the reason was to make docbook the official tool for documentation. (I should probably try to look it up in the mail archives, but don't feel like that right now.) So if you manage to bridge between
Archives were lost since then so it's not easy to look at them :(
Back then, Docbook had the advantage of being transformable with XSL to any content we'd like. We thought to Doxygen in a way to generate API documentation, but it didn't have something really better than Docbook in its use, apart its ability to parse source files for doc tags. Now, the generated XML from Doxygen could be used to generate API docbook files. About the Docbook syntax, I don't think it's hard to learn and write, particularly if there is already a load of samples to reuse.
The Boost XSL sheets used to convert from Doxygen XML are already in our repository. It's not easy to integrate them and structure the book.