Re: Documentation

<mj@php.net> wrote : > On Sat Apr 26, 2003 at 11:1357PM +1000, Matthew Palmer wrote: >> On Sat, 26 Apr 2003, Daniel Khan wrote: >> >>> ACK - BUT what can be done to solve the problem? >>> There is no realistic way to force one to write a propper docu. >>> And to demand a full docu on package proposal isn't the right way either I >>> think. >>> What shall be done with existing, important, packages without docu? >> >> Deprecate any package which does not have at least some attempt at >> documentation. Allow and encourage properly documented replacements for >> undocumented packages. Do not give approval for packages which do not at >> least make a token effort at documentation. Put in the PEAR coding >> standards (in fact, I think it's there already) that if it isn't documented, >> it effectively doesn't exist - to the point of not allowing it into the >> downloadable part of PEAR without being checked first for documentation, if >> that is necessary. > > http://pear.php.net/~mj/004-documentation.txt might be of > interest for > you. Hi Martin, I agree with this, I would just add that at the moment, there isn't any reward for people to write packages documentation. Documentation author names and emails should be added in the package description or on the documentation page. This would maybe encourage some users to write or contribute documentation to the package they know well. My 2 cents, we might discuss this further at the meeting. Bertrand Mansion Mamasam