On Sat, Dec 18, 2010 at 1:52 PM, Steve Holden <[email protected]> wrote: > On 12/18/2010 4:32 AM, anatoly techtonik wrote: >> The best course of action is to allow site edits by users. > > That's an opinion, but not the only one. Have you seen the PHP > documentation with user comments? The comments render the documentation > less useful in some cases.
Comments were extremely useful some years ago, as they had a lot of actual examples, which greatly saved time. When I was working on Extended CHM version of PHP manual https://students.kiv.zcu.cz/doc/php5/docs-echm.php.html user comments were one of its major features. >From my learning experience user feedback in comments was more useful than outdated documentation. The feedback that Python still lacks. I tried to start Python several times, but until I found Python Cookbook, I couldn't understand a whole world of concepts behind the language. Maybe that's the goal - filter people, until they are proficient enough to understand the language? There was no cookbook for PHP - all recipes for most common problems were in comments. Right now the system may be outdated. Comments are moderated, but even long ago there were so many requests that nobody really had time to review and approve them all. The comment system could evolve to allow users report outdated info and rate comments, but those who became capable to enhance the system grow out of PHP. People switched to Experts Exchange and now there is StackOverflow. My opinion is that documentation should be edited online, and right now it is possible to make at least documentation edits more accessible. My ticket for "suggest a change" link is waiting somewhere on bug tracker. Idea is there, moderation queue algorithm is there, patch system is ready, even rendering is partially there. But nobody wants to see the system as a whole, so proposals like "immediate doc build system" are closed. I must say that there is no framework for collaboration. People are concentrated on specific bugs and work alone, but complex issues require coordination, and nobody seem interested in that. Not interested, because there are many open questions, before you start contributing, and if people can't find the answers, and don't have time for discussions, they are unlikely to be involved. For example, let's take the main questions for most open source projects - licensing of this collaborative work. Why should I participate? What do I get in exchange? Can I reuse that I've done? After the last time I tried to discuss it, my patches stopped to be accepted, so I don't write them anymore. For all open source projects it is clear that if project is MIT licensed your patch will also be MIT licensed, isn't it? Some time ago I opened a project on http://code.google.com/p/pydotorg/ to draft a collaboration platform I'd like to see for pydotorg. It is not ideal, but sets some standards that python.org fails. I hope it clearly communicates the ideas of reuse and cross-project collaboration. If only smb. else was interested in these.. But at least people are free to add and star proposals. -- anatoly t. _______________________________________________ pydotorg-www mailing list [email protected] http://mail.python.org/mailman/listinfo/pydotorg-www
