Re: Is your package really documented? The truth

On Apr 30, 2004, at 4:38 PM, Bertrand Mansion wrote:

David, The fact that you are working on writing missing documentation is very good, that's not what I am worried about. It is also great that you are volunteer to convert wiki written documentation to docbook. Thanks for your appreciation.

But I think that's maybe relying on you too much and one of these days, you might be too busy to take care of that, especially with 139 (and more coming) missing docs.

Well, I am not meant to document 139 packages nor to convert wiki documentation to docbook ;-) The idea is another, as I did on some packages (Text_Wiki, Mail_Imap) this solutions allows in the immediate, to use a Wiki to keep your docs, yet to let the users know, on the manual, some basic information with a link to a living documentation maintained by the developer-package leads. It also allow the developers to receive immediate feedback (e.g. using yawiki which is well done and support comments on the fly) on their package and change thinks immediately without having to sync with the manual.

So at the moment, I see your solution as a placebo to a bigger problem. If in the end everything is written in the wiki, then why not use the wiki directly ? Because nobody has the time to code one at the moment. When we will have a group wiki, which might be the case in the future, it would be fairly easy to

migrate the external docs if necessary. And of course, because I can't do that. As I said if you/someone writes a system on these lines, I assume that the group will have no problem to run a call for votes and see how implementation can be done. But please think about it. The users of one of the not-documented package might not be willing to wait, and might just hang around on the several forums saying that PEAR is bad because is not documented. This is not true, many packages are documented externally (e.g. I counted the Math packages not documented, but these are documented and linked on the package page. They are however not documented for a user browsing or downloading the manual).

IMO, a specialized CMS is the solution. Unfortunately, this does not exist yet. yes I agree, and seen that the developers have not enough time (this is a common problem nowadays) I don't expect someone to come with an alternative specialized CMS

soon. Thanks again for your feedback. Every constructive criticism helps, if it wasn't for Paul who did pushed the alternative idea, I wouldn't have bothered in looking on the matter in mode details. Anyone else willing to do his docs, in any format ? :D Cheers David Costa

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