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

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

Please tell me why we shouldn't drop docbook.

Because Docbook is technically the right tool for our needs.

I ask again, "What are our needs?" I don't mean to nag, but has anyone really listed our requirements? Requirements first, technology later. I attempted to list requirements earlier in this thread, and I will list them again here:

I would argue we have these minimum requirements: 1. Easy online collaboration between identified participants. 2. Ability to allow/deny specific users access to specific documents (particularly for editing). 3. Easy to learn the markup to lower barriers to entry (docs are less sexy than code, let's make it easy to get into them ;-) 4. Easy to translate the document source to multiple output formats, targets, and languages. 5. Fast turnaround between edits and displayed results. 6. A comment system so that users who are not allowed to edit directly can still be heard within context. What are the other requirements for the PEAR document creation/editing/delivery system?

Is there anything I missed in that list? Are there things in that list which do not belong?

DocBook fits the bill. It is easy if you spend some time learning it. The same system is used on php.net main and LiveDocs might be a possible replacement (for the fast turnaroud) but I don't see anything better at the moment. The problem is authors, not the format. PHPDocumentor has an excellent GUI where every lead can produce some basic XML documents. Once again, in my humble opinion the problem is not the tool but the limited number of volunteers willing to spend time with docs. This would not be a problem if every lead would do some basic docs for his own package. Cheers David

-- Paul M. Jones Savant: the simple alternative to Smarty. http://phpsavant.com/ -- PEAR Development Mailing List (http://pear.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php