Re: Online doc generator (Was: Re: [PEAR-DEV] Amsterdam meeting agenda)

On Apr 12, 2004, at 5:54 PM, Paul M Jones wrote:

<snip>

That is not an answer to the question; you are talking technology, not requirements, and skipping vital parts of the decision process. I am talking requirements too. I don't see any of your requirements to be incompatible with docbook or livedocs.

The problem is authors, not the format.

The two may be related; in fact, I would argue they are intimately related, along with the mechanism for creating, editing, and generating the docs.

Don't get me wrong, I am very open to alternatives but I am not aware of any reliable alternative at the moment. The main PHP Documentation is builded with docbook and you can't really say that php is not well documented ;) I don't think that there is such a relation at the moment. Many developers are simply not very keen on writing docs (and this is understandable) so the best solution for now would be the automatic generation of some docs for each package. I appreciate your effort but we can't just implement a totally different platform unless it does present some huge advantages. If you know any application which might do the job in a better way feel free to let me know, I would be more then willing to test it. Another advantage of DocBook is the generation of the manual in different formats. The learning curve is not immediate but if you/ a lead reads the http://www.php.net/manual/howto/ it should be a few days work to learn it. I have yet to see some documentation (even in word, text format, html, you name it) posted to the pear-doc list from a developer. Yet many developers (Alexey, Dan) provide an excellent documentation for their packages, docbook or not. This is why I doubt that things would change that easily, even if you change the doc system to something dead easy to use like a simple wiki. Cheers David Costa