Phillip and I had a chat about this last night and I think we have a strategy for appealing to the geek in all of us.
-Rasmus Mehdi Achour wrote: > 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 >> >> -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
