Forum OpenACS Q&A: Re: Best markup language? DocBook, Scribe, Wiki, HTML, LaTex, or etc.

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.
  1. Download the documentation source code
  2. Use a decent editor for docbook (I used emacs) to edit the documentation. Make sure you keep up the markup
  3. Generate the HTML out of it
  4. CVS commit both files to the repository
  5. Make sure you are on the correct branch. Commit again 😊
  6. Write an email to Joel to update the documentation on openacs.org
  7. 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
  1. Login to openacs.org/wiki/documentation
  2. Edit the documentation
  3. Reflect in glory about your excellent work
it seriously lacks user friendliness.