As Phillip stated, we already have a set of tools that points us to the problems in the documentation.
We also are switching the documentation to a clearer format, which we help us to have more accurate results on this, while making docs editing simpler for you guys. I've noted your periodical update proposal. Indeed, a wiki page on phpdoc.info could help to prepare a weekly email to internals (with some statistics like the one Phillip gave us). Thank you all for your replies, I'm happy to see that the snowball effect started! Mehdi On 2/10/07, Rasmus Lerdorf <[EMAIL PROTECTED]> 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@ -Rasmus Ronald Chmara wrote: > On Jan 27, 2007, at 8:26 AM, Mehdi Achour wrote: >> Hello internals, >> I've been helping with PHP documentation for 4 years now, and I still >> can't help the fact that a loooot of things are not documented, that >> our/my way of handling the PHP documentation update is not accurate, >> nor productive, nor bug free at all. > > I think it's been ~7 years of off and on work for me... same as it ever > was. I do think it's *much* more productive and accurate than it was 7 > years ago, though. Not quite bug-free, yet. > > (You think it's bad now...) > >> Personally, I try to follow commits on php.cvs, bug reports, Change >> Log?, user notes on the online manual.. but I still have the feeling >> of missing a lot of changes. After a year away from the project, I >> have _no_ clue what was added, when, and whether it was added to our >> documentation or not. > > You are in the same boat as me..... The dunes change, but the sands are > always shifting. I might have been away for n years. Much has changed, > and much has not. > >> I know that you developers are willing to help a lot with it, but that >> you cannot manage to save the spare time needed to do it the right >> way. That's why I would like to propose a simple/small/timeless change >> in your CVS commit messages: If you feel that the change need to be >> documented, place the @doc keyword at the end of your message log entry. > > Scenario one: > All behavior changes must be documented, this tag is always there, and > thus not useful. > > Scenario two: > Developers decide when changes are "important" enough to be documented, > and tag as such, in which case we go back to... > > Scenario three: > The problem of developers who don't think documentation is needed for > their changes. > > In the end, I often wonder if this is documentation issue, or a > developer issue. Developers read the code, and often don't need *any* > documentation. Our end users read a manual page, and wonder what a > "bool" or "int" is, as a very large number of our users are fairly new > to the whole subject matter. > > (side joke, does PHP have a zool(), destroyer of all world (global) > variables?) > > Anyways, to me, the real challenge of working on the PHP docs is not > getting programmers to feed us reliable, consistent, data all the time > (they won't), but rather, helping out our end users who don't read > source code. > > Vanity devs will want us to document everything, quiet devs will never > tag it. > > In the end, the doc team still has to fix it. > > -Ronabop > > --PHP Internals - PHP Runtime Development Mailing List > To unsubscribe, visit: http://www.php.net/unsub.php
