Re: Is your package Documented ?

On Apr 13, 2004, at 9:25 PM, Paul M Jones wrote:

On Apr 13, 2004, at 1:48 PM, David Costa wrote:

Is you package documented and listed in the pear manual ?

Thanks to David Costa it is (kind of) -- David just linked the manual entries for Text_Wiki and Contact_Vcard_* to my external documentation site.

great, may be you can add more examples for dummies on your own site? Like for instance, I am interested in Text_Wiki but I would love more examples on http://wiki.ciaweb.net/yawiki/index.php?wiki=Text_Wiki&page=SamplePage Like, I want to build a wiki, how does text wiki saves me time ? :D (perhaps is just me knowing little about wiki's but I am really interested)

If the answer to this question is No, please let us know why not ;) (email the Doc list at pear-doc@lists.php.net)

I think I've been hammering at this one a while on PEAR-DOC, but I'll say it again here (as Jones the Ogre!) -- I find it far too difficult to get started in the current documentation system, and the feedback loop is much too long to be rewarding. That's just me.

Fine. I think we should/could give developers alternatives. Your wiki is a good example to me of a good external documentation where a user can post comments et all. I think we can make the docs better starting from now (regardless of the platform) by writing these in DocBook or your favorite wiki in your website. Let's just have something. Think about it, if I just browsed the manual with no text_wiki listed I would not even know it exist unless I visit the packages section ;)

Extensive documentation (whenever possible with clear, "for dummies" examples) is critical to ensure both your package and PEAR success among users.

Absolutely right.

Documentation can be automatically-generated using PHPDocumentor http://pear.php.net/package/PhpDocumentor/

Jones the Ogre speaks: PhpDocumentor itself is not in the PEAR documentation. Is that bad? :-(

not bad but if it helps to document your code from the comments it's a good thing. Still you have to write some examples etc. Again, I am really more into the "let's do it" mindset then "let's think it" :D

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