Re: Lack of docs: reality check

On Apr 13, 2004, at 4:15 AM, Alexey Borzov wrote:

To those who feel that PEAR lacks docs because of DocBook format: have you *ever* seen a developer posting a message along the lines of "I *wrote* these cool docs, available here, but am unable to convert them to this horrible DocBook"?

I'll say that right now. I am a big fan of documentation, but DocBook is horrible to get started with. It might be easy once you know it, but getting to know it is entirely too much work. I would do lots more documentation within the PEAR system if not for DocBook (the rest of the system is not too hot for doc-n00bs either, but doc-n00bs are the ones we need to court).

Clarification: it is quite different from "we *will* write docs, honest, if it wasn't for DocBook".

I spend as much time on documentation as I do on code (check out http://wiki.ciaweb.net/) but not in DocBook format, because the reward-to-effort ratio is far too small. -- Paul M. Jones Savant: the simple alternative to Smarty. http://phpsavant.com/