I will share my experience in Docbook and Doxygen, it was when i coordinated elementary teachers, a months ago, in some educational documentation, where the terms 'psycholinguistics', 'sociolinguistics' and many literal quotes were involved. The result? Doxygen is so much easier to learn and to use. Period.
In the opinion of the teachers, it was a lot simpler to handle. Even the 55 year old teachers understood Doxygen. We made the output in HTML, in PDF and (who of us could imagine it?) the printer guys prefered Doxygen when we had the final paper.
Let's face it: although you have to remember what are you doing, as a non-programmer you can do Doxygen. To be honest, i use third party software to write docbook, because _it's not made for everybody_.
My point is: since the very beginning it has been said that non programmers could still help with documentation, and, until today, there is no how. The wiki (for writing user documentation, as everybody understood) is down. Using docbook is hard, please, let us avoid that issue. Let us, non-skillfull-programmers, contribuite somehow. Let everybody to write even in Visual Notepad, gedit or in their handheld plain text editor, if they want to.
A very wise man told me to understand how the BeOS works, then to learn C++, which i am doing with many efforts (but i am on my way), in order to do better documentation of the API when the time comes. If there is anything we need to learn, the API is, not particular parser rules. The thing we need to focus are on the classes, not in the picky method prototypes, the proper levels... the API. The API is.
Thank you so much for taking my opinion, Niels. We look for the best way to do it as Haiku does: easy for everybody. Be well.
Miguel Zúñiga González
