Getting up to speed on docbook took me half a day for being good enough to write OpenACS documentation. Then it took me again half a day to figure out how to use the provided scripts to generate HTML out of the docbook file. So it is not a problem of the Docbook format. It is more a problem of the steps involved which will scare the casual user from editing documentation.
- Download the documentation source code
- Use a decent editor for docbook (I used emacs) to edit the documentation. Make sure you keep up the markup
- Generate the HTML out of it
- CVS commit both files to the repository
- Make sure you are on the correct branch. Commit again 😊
- Write an email to Joel to update the documentation on openacs.org
- Realize Joel is busy, login to openacs.org and do the update yourself (This steps used to work for OCT members, now this is restricted to even less people).
Compared with
- Login to openacs.org/wiki/documentation
- Edit the documentation
- Reflect in glory about your excellent work
it seriously lacks user friendliness.
