Advantages of DocBook:
1. automatically generates chapters
2. outputs to PDF and other formats, I believe.
Disadvantages of DocBook:
1. Another learning curve. Developers are already loath to document their work, and it adds another obstacle in the path.
Personally, I think any sort of documentation we host on the website should be editable like an ETP instance, with access limited to a select group. That's the easiest thing I could imagine.
It's only because ETP makes it so easy that I've added so much documentation to OpenACS on my own site: http://rubick.com
If it was that easy, I'd volunteer to help with documentation.
The nice thing about this is that it also takes advantage of skills we already have: knowledge of HTML.
And when we get Wiki style input in ETP, producing documentation would be really really easy.
Is there an easy way all the documentation from ETP could be copied to a local instance, or output to HTML, so that local copies of OpenACS would have the documentation as well?
If we are going to choose DocBook as a standard, then we need more documentation on how to use DocBook, and how to document an OpenACS project, with templates, etc.. I tried it a couple times from the tutorial, but gave up, because it seemed like my computer wasn't set up right for DocBook, and I didn't have the time to figure it out.
