Forum OpenACS Q&A: Re: Docbook a barrier to doc efforts?

Posted by Andrew Piskorski on
DocBook is certainly an obstacle to generation of OpenACS related docs, articles, etc. (Yes, we have skilled volunteers willing to manually merge non-DocBook content into the DocBook sources, which is excellent, but that's still not and can't be the same as being able to yank the sources from CVS and fix things yourself.)

How big an obstacle I can't really say, as I've never tried using it. Maybe big, maybe small. But I think I've only ever met one programmer who, by choice, preferred to write in DocBook XML.

Part of that is probably path dependent. (E.g., I also know programmers who use and like LaTex but never HTML; but is that because LaTex is better/easier or just because they already know it and don't care to bother with HTML?)

But still, that sounds like a somewhat telling piecee of circumstantial evidence against DocBook to me.

I'd say that for doc formats and tools, priority should be, in order with top priorities first:

  1. Lower barriers to entry, encourage as much contributed content as possible.
  2. Higher quality of docs (e.g., auto-generated Table of Contents), better and easier maintenance of docs.
  3. Better and easier conversion to multiple output formats. (AFAIK to date this has never been a real priority for any real user of OpenACS, and isn't likely to become one either.)