Re: RFC: Commentation- and Rating-System für PEAR-Websites

> On Wed Feb 26, 2003 at 08:4028PM +0100, Tobias Schlitt wrote: > > The idea is pretty simple. Because of many PEAR packages having > > no online-documentation and to complete the existing examples > > their should be IMHO a possibility to leave some comments on > > each package. I think the best way is to link the comments > > together with the packages themself (respectively the > > corresponding webpage with closer information) and on the other > > hand with the corresponding manual-pages. (Whereupon we have to > > think how manuals with multiple pages should be linked). > > Having such a system will make most developers write absolutely no > documentation for their package, because they expect their users to > leave some comments instead. I'm -1 on this. The biggest problem is getting the documentation out to the end user... er... end developer ;-). A lot of questions that are asked on pear-general could easily be put on a comment list, kinda like on the php docs. When I started using PHP, I don't know how often I looked through the comments in the manual because I was looking for an example of how to use a function in a very specific way. Developers are sloppy with documentation anyway (esp. if it's not required to be as verbose for general pear as for PFC), and it won't ever quite keep up with the development. Inline docs are great, and admittedly they are more accessible than looking at the source for PHP itself ;-) But, I still think that we need to have a clear, _concise_ documentation page, that lists the methods and their functionality, much like in the PHP docs. I don't see why this is such a big problem. It seems to me to be an advantage to allow users to comment -- especially for packages not in the PFC, where the author might not have spent much time on documentation. Not only that, a workaround for a bug may be placed on the comments and removed as soon as the bug is fixed -- or better yet, edited to say that in a certain release, it's fixed. That will be advantageous for everyone, because you can't expect people in a production environment to upgrade the package, esp. if it means that more features have been added. If it's not broken, don't fix it :-) Klaus