Re: Re: PEAR Descriptions/More documentation

Hi, I have to apologize, but I don't have the original posting of Chuck: http://marc.theaimsgroup.com/?l=pear-dev&m=100257550704402&w=2 | No. That's the best that _you_ can do. I tend to learn at least as well from | API docs. Someone else will learn a different way. Lots of people prefer | tutorials like you do; lots more prefer API docs. Probably most would rather | have both. Well, think about what quality PEAR would have if nearly every Package could come with its own (little) tutorial about how to use the package. Imagine a short tutorial with "3 steps on how to use Net::Socket to create a PHP daemon" integrated into the package. I know, developers are generally lazy folks and don't like to document things or even write articles, tutorials etc. Imagine further the impact a clean documented PEAR (I mean the packages itself) would have on the public image. With it you can't say "Well, it's a crowded house of PHP code only with API docs, use the source, luke and die.". Instead you can say "Look, here's PEAR, look here you can get the API docs and look nearly every package has its own short tutorial." - This reduces the time the developer has to get in touch with the package (reducing TCO) and it increases the value of the package. Imagine a crowded package that only exists of its API docs and nothing more. Imagine further this crowded package is more than a simple "Hello world". Imagine a developer looks for such a package and wants to use it. He thinks: "Oh dear, why are there only API docs, I need days to fully understand how to use this package. I think its better to write my own thing." -- this torpedoes the aim of PEAR to be a pool of packages everyone should use (and to avoid NIH (Not Invented Here) behaviour). Of course, if we all mutate to BOFHs, we can say "API doc is enough, RTFM, use the source". But having only BOFH behaviour hurts the image of PEAR and PHP. One remark to the "Should we use DocBook or not?" discussion: I think it is counterproductive to discuss the format of such documentations *for days*. To bring people forward to write Tutorials for their PEAR packages you mustn't have a high entry level in writing such Tutorials. Saying "You must write in DocBook" *is* a high level because one has to learn DocBook ( .oO("Oh dear, I have to learn DocBook, that's shit, I think I won't write any tutorial, people should RTFM or die.") ). So you have to lower the entry level. -- PHP- und MySQL-Schulungen. * Kontakt: * Consultingdienstleistungen. * * Managementseminare als Entscheidungshilfe * team@thinkphp.de * zu einem möglichen Einsatz von PHP und MySQL * 0931 / 78 43 804 *