improving the Python docs -- a wiki? copy PHP's model?

[Andrew Bennetts]

On Wed, May 05, 2004 at 06:16:06AM -0700, Stephen Ferg wrote:
> > Is submitting a bug or patch to sourceforge really that much of a barrier?
> 
> Yes, it is a significant barrier.  It requires knowledge of both Latex
> and a certain way of using diff.  There are many, many Python users --
> especially Python-on-Windows -- who are not familiar with these
> technologies and don't have the time to learn them for the sole
> purpose of making a contribution to the documentation.

This is demonstrably false.  I've contributed to the docs with a bug where I
suggested a sentence or two that should be inserted, and that was sufficient
for my text to make it into the docs.  No diff, no LaTeX.  I doubt I'm
alone.

> > As a reader, I
> > prefer properly written and edited and officially approved documentation to
> > ten pages of advice from people I don't know ...
> 
> I agree.  But there are gaps in the documentation, where the
> officially approved documentation is silent.  In such cases, I prefer
> advice from others, even though I've never met them, to no help at
> all.
> 
> After all, what is comp.lang.python except advice from people that
> you've (for the most part) never met. :-)

comp.lang.python is also a place where you can already most likely find
advice on pretty much any un- or under-documented standard library module,
if you check the archives.  So even here we have everything the PHP docs do.

> > I've never felt that the Python documentation was particularly lacking...
> 
> In general, I'd agree that the Python documentation is outstanding. 
> But there are gaps -- a qualifying phrase here, a missing reference
> there, a small example in many places.  Filling those gaps would make
> the difference in those places between documentation that is just
> barely adequate and documentation that is really excellent.

You seem to know of several cases of these -- so submit bugs about them!  No
diff or LaTeX required, as explained above.

[...]
> 
> WE NEED TO MAKE IT EASIER FOR MANY HANDS -- INCLUDING NEWBIE HANDS --
> TO CONTRIBUTE TO THE DOCUMENTATION.

This is problematic.  You're quite right that newbies rely more heavily on
docs than experienced users, and so they're more likely to find any problems
in the docs.  But they're also the least qualified to know how to fix it
(as amply demonstrated by your, ahem, "impressive" example of PHP's docs on
sorting arrays).  Because of this, newbies generally should be submitting
bugs, rather than offering patches, an activity that clearly needs no diff
or LaTeX.

I realise I'm sounding repetitive here, but: The only barrier is being able
to submit a bug to the bug tracker.

> The PHP model is a good one.  Many hands contribute online. 
> Periodically, expert hands incorporate the best of the online
> contributions into the mainline docs.

How long is that period?  The example you gave had comments that were
several years old.  How many releases of PHP have there been since 2000?

-Andrew.