Re: Re: Improving the documentation

On Feb 10, 2007, at 8:38 AM, Rasmus Lerdorf wrote:

We, and by we I mean all of us who write code and hope that divine intervention will take care of the documentation, need to do a better job helping out divinity. A DOC tag in cvs commit messages seems like a small and easy thing for us to add to the process, so if you feel that will be enough to make things easier, let's do that. Perhaps we can do more though. Maybe you guys could periodically update internals on problem areas in the docs. Places where you feel things are vague and really could use the guy who wrote the code to get off his ass and explain how it works. Or maybe we could get everyone who reads internals to pick a page or two in the manual on something they are intimately familiar with and go over it in detail and feed suggestions back to phpdoc@

There are 137 open documentation bugs and many of these require PHP internals intervention. I don't know the best way to help that happen aside from maybe going through them all and updating the summaries (and appending categories to those summaries) but then what? A question: What would be a productive way to help get 'er done? Side note: Is it time to completely overhaul php-bugs-web? (I'm not volunteering!) Those ideas about doing more are nice because the DOC tag is a good start but additional collaboration is needed. Part of the documentation teams job can easily be organizing information requests so the developers can work efficiently. If that means, as suggested above, periodic updates then we'll for sure do it. A few come to mind already. It's exciting to see this thread blossom! I hope everyone feels free to brainstorm... ALL ideas are welcome! A rough unofficial related report: Undocumented functions (only proto, etc.): ~815 Functions not in the manual: ~118 (granted ~half are ref.unicode) Functions missing examples: ~2490 Open doc bugs: 137 To those interested in seeing where exactly these statistics came from, have a look: http://doc.php.net/php/ Regards, Philip