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

Moving this to PEAR-DOC per Lukas' request, folks, when you reply remember to remove PEAR-DEV from the recipients. On Apr 12, 2004, at 11:28 AM, David Costa wrote:

Don't get me wrong, I am very open to alternatives but I am not aware of any reliable alternative at the moment.

That's why we need to do requirements determination. Your "reliable" may not be the consensus "reliable" (just for starters).

I am sorry but I just expressed my opinion. I am a mere volunteer and I never pretended that my "reliable" reflects the views of the majority.

No apology needed, man, and I'm not slamming you. I too am one of the lowly unwashed. :-) Of course you're not speaking for the group, and neither am I; I was not impugning your statement. This is why I'm reiterating the need for a requirements list: find out what we really need, from a requirements point-of-view, and then we can pick a good technology for it.

Step 2 will be to figure out what meets the requirements. Wiki might, DocBook might, ReST might, New Silver Bullet X might. But requirements first! DocBook is not a "requirement", it is a technology solution, same as Wiki or anything else.

One of the main arguments (for me) to stay with DocBook is that all the time invested to migrate the existing Docs to a wiki or something else can be deployed to write either a set of very simple tutorials for developers or some skeleton XML where the lead has just the duty to fill in some of the tags (this is already achievable with PHPDocumentor to some extend) or even better to auto generate some docs with PHPDocumentor.

"Sunk costs" are not a valid decision strategy. The costs we have sunk into DocBook are irrelevant; whether we choose to stay with or depart from DocBook is not related to how much we have used it already. No matter if we stay or depart, we can't get that time back. Our future time may be better spent with another solution. If sunk costs were a viable decision strategy, we would be programming in COBOL, not in PHP. We can best determine our future course only by knowing where we want to go (i.e., requirements).

The second argument is that Docbook is used by php.net and I can ask for some help there if needed.

PEAR is not php.net. Their requirements may be different from our requirements. What are our requirements? I will list my idea of the requirements for the benefit of the new PEAR-DOC thread; they may or may not be complete or accurate.

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?

-- Paul M. Jones Savant: the simple alternative to Smarty. http://phpsavant.com/