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
  7. Realize Joel is busy, login to 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
  2. Edit the documentation
  3. Reflect in glory about your excellent work
it seriously lacks user friendliness.