[pydotorg-www] Fwd: A little mistake, Agustin

[anatoly techtonik]

On Sat, Dec 18, 2010 at 1:52 PM, Steve Holden <steve at holdenweb.com> 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.