Sean Coates has posted a rant and a blog entry regarding DocBook and the various proposals on PEAR related to using a wiki for package documentation.

A little background is probably in order. Many PEAR developers feel that DocBook is needlessly difficult and provides a barrier to writing good documentation for PEAR projects; this is actually the most often-cited reason for lack of documentation for a PEAR package. Many actually create wikis that they then link to in a minimal DocBook tutorial as "full documentation".

One proposed remedy is to create a PEAR wiki for each PEAR package. A scheduled process would then transform the wiki markup to DocBook, HTML, PDF, whatever.

What Sean rants about is simply this: wiki markup is meant to be simple, and much code documentation would require specialized wiki markup. Additionally, DocBook is already meant to do the transformations required; it is a structured language that is meant to be processed into a variety of output formats.

While I agree with Sean's ideas in essence, I still feel that DocBook is a real pain to work with. PhpDocumentor offers some real convenience when documenting code: doc blocks can contain HTML, some simple inline elements like {@link} — and they make documenting a snap. But I just fail to understand why, when providing tutorials, a switch to DocBook is necessary. Whenever I use it, I find that I have to retool a set of tutorials I have, or somebody else has, already written in order to get formatting correct, and that I have to switch my thinking altogether to accomodate a new set of rules and logic.

Yes, DocBook is simply XML with a documented schema. However, I've never enjoyed XML. I find it too pedantic, I don't like having to escape out CDATA sequences in order to render HTML (and code, and XML, etc.), I don't like having to learn new DTDs for every project, and more. I feel for configuration, unless you have nested elements, there's no reason to use XML whatsoever. And when it comes to documentation, why use anything other than HTML? Since HTML is a subset of SGML (as is XML), there's no reason it can't be transformed to other formats itself — and for the majority of PHP developers, HTML is a known, while XML/DocBook may or may not be.

Whether or not DocBook is hard can be debated from here to eternity. The fact of the matter is that it is perceived as being hard to learn, and thus many PEAR developers are simply choosing not to bother. Why not give them a tool they can use easily? Maybe then the amount and quality of documentation on PEAR will improve.