Re: Is your package really documented? The truth

Have we (PEAR) looked at the PHP livedocs yet? [1] They are instantly updated documentation which uses the DocBook from the current PHP manual... seems like a good solution. We should now be moving to the same DocBook version as PHP, we use (IIRC) a customised DocBook 3, I understand the choice was because at the time the PHP DocBook didn't need much OO documentation. With the introduction of PHP5, this has obviously changed - they are now using DocBook 4 (again, IIRC) - which has the capabilities to document OO sufficiently. If we move to DocBook 4, the same as the PHP Manual, we'll be able to use livedocs and see our results instantly :) - Davey [1] http://docs.php.net/ David Costa wrote:

Dear Bertrand, thanks for your feedback. See my comments below: On Apr 30, 2004, at 9:59 AM, Bertrand Mansion wrote:

We have 139 not documented packages at the moment (including alpha and beta releases)

I knew the figure was high but here, I am pleasantly surprised !

yes but we will take it down soon, I don't get the pleasant surprise of finding many undocumented packages, but anyway.

Possible solutions: a) learn DocBook format and validation, use PHPDocumentor to prepare your docs and commit to peardoc b) Prepare some basic docbook documentation (see http://pear.gurugeek.org/ for an explanation and some examples) which links to your website or better a Wiki where you have available both the API Documentation and some implementation examples. I am willing to do the PEAR Manual/Docbook linking and basic documentation on demand. Looking forward your suggestions and comments,

None of your proposed solutions will actually solve anything.

I think it will solve part of the problem. I personally added around 10 packages this way (8% of the non-documented one more or less) and at this rate I can bring the percentage to 16-20% in a couple of months. Of course if you do have a better solution, let me know.

You are standing in front of an alarming situation and you keep on proposing the same old things as before.

As far as I know is the first time when someone is saying "do the docs with a wiki, with any format you like in your own site, and I will do the rest linking it to the manual" but I might be wrong.

You keep on thinking the problem is that people don't know how to use docbook. Even a monkey would know how to write docbook.

I don't usually work with monkeys but I had the chance to deal with other PEAR developers that, like me, have to cope with work, family, personal interest and an array of priorities. Some of them tried docbook and for a reason or another would prefer a wiki or an alternative. This is a fact. Some experienced PEAR developers keep their documentation outside the manual in another format. This is an indication that they simple don't have the time to dig further on docbook but are willing to provide the documentation for their packages. To some, specially small packages, it is fairly simple to produce the HTML API Documentation using PhpDocumentor but is a bit harder to make the XML docs and validate it locally. You can't easily validate docbook docs if you run windows.

I think it is time to realize that the problem is not the format but the interface. Use whatever you want to store the data, whether it is docbook or reSt, who cares, but provide an interface that works, that's easy to use, that allows WYSIWYG like editing and where you don't have to wait a whole week to see you made something wrong.

This is exactly what I proposed as an alternative, do it on a wiki (which fits the bill of an easy to use, WYSIWYG editor, and don't have to wait a whole week) and I will take care of the docbook deal. We already discussed the possibility to change the interface but we didn't find someone willing to say "I will do it, here is my draft, here is my system" so I decided to propose my alternative which can work from now, tomorrow, anytime. I am more then glad to look at other proposals.

And BTW if PEAR wants to continue to use Docbook, it should use at least a standard version, not an old custom incompatible one.

Bertrand, I do have a great deal of respect for your work and contribution to PEAR. I am very aware of the fact that my proposed solutions are nothing fancy, but I did actually spent many hours to produce the list you see on the wiki http://pear.gurugeek.org and I did my very best. That said, you can (and everyone) come up with a different solution. Not an idea, but a solution where you or someone you know will actually do the work. There are a lot of ideas on Peardoc. Paul helped me with the wiki idea, and now we have a status page. I can't imagine myself re-coding a new system where docbook does the job and I can't imagine anyone moving all the docbook xml stuff into another format. If you want to do it, by all means. Cheers David Costa

Bertrand Mansion Mamasam -- PEAR Development Mailing List (http://pear.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php