Documentation requirement (was [Call For Votes] PHP::Fork)

> On Sat Nov 08, 2003 at 11:2521AM +0100, Stephan Schmidt wrote: > > > Sounds fine for me. However I'm only +1 on this when there is end-user > > > documentation in plain text or Docbook. (That's one of the > > requirements > > > for contributing new code, btw.) > > > > You can't be serious! > > Adjust your tone. Thanks. I think you took this harsher than intended. In English, an exclamation like this is not insulting, and merely indicates negative surprise. Please accomodate others. > > Does this mean that a developer has to write > > complete documentation before a pakage will be accepted? > > "Documentation in an appropriate format (plain text, docbook) > > Your code must come with appropriate documentation in one of the > following formats: > > - Docbook XML > - Plain Text" > > (http://pear.php.net/manual/en/developers.contributing.php) > I agree with Bertrand. This requirement is absurd. If it is a requirement for a stable release, it's good. But if it's a requirement for package acceptance, you'll have to wait till the moon turns blue before people will submit packages. I have two packages that are as yet undocumented, though they have sufficient inline docs. I'm still waiting for Greg's answer about inherited methods and phpDocumentor. Speaking of which, there has to be a documentation solution for packages that inherit methods. My classes, for example, extend HTML_Common. I don't think it makes much sense to create redundent documentation. As it now stands, all documentation must include inherited methods and properties. This is completely absurd, because if the api of the parent class changes, you have to change the documentation in a million places. It's hard enough to get people to write documentation once without updating it whenever the parent class changes slightly (e.g., new methods and/or properties are added). I'd like to see a dynamic documentation solution that includes public methods and properties for all inherited classes. Of course, if I replace a method, it should overwrite the docs for the inherited method. And this should be transparent for users. Right now, you have to hunt all over the world to find even the most basic stuff. It's easier to read the source code (note: when I program, I have my browser at cvs.php.net rather than pear.php.net/manual). Unless documentation is simplified and comments are added, you can forget having a very broad userbase. Google is better than the pear manual. Even for well documented packages. Wonder why people ask basic questions on the ml... if there were online comments, the pear-general traffic would decrease substantially. It's beyond me why people insist on doing things the hard way and punishing the developer rather than empowering the user. The php manual is doing it right. If the documentation is lacking, people will add comments (of course, the php manual is very complete in itself, too). These comments can later be included in the documentation. If I need to spend all my time writing documentation before my package proprosal can be accepted, you can forget me spending time in development. I'll simply phpdoc my code and use it myself rather than sharing it. I think that's the position of many developers who would be very willing to write the documentation once the api is stablized. If I document a _very simple_ 0.1 alpha release to get it accepted, is there any requirement that I document the 1.0 stable release that has an api that is completely different? We need to address the real problem, not strain at gnats and swallow camels. I know that user comments have been brought up before on here, and iirc a solution is being worked on. That will substantially help. Also, a _real_ documentation solution is needed, one that even inexperienced php coders can understand. Only so can we achieve the broad user base we are so eager to have. Klaus