Python docs disappointing - group effort to hire writers?

Roel Schroeven rschroev_nospam_ml at fastmail.fm
Sat Aug 8 08:39:49 CEST 2009


Paul Rubin schreef:
> Steven D'Aprano <steve at REMOVE-THIS-cybersource.com.au> writes:
>> As for the rest, you're right that the current bug-tracker puts up 
>> barriers to people submitting comments and bugs. That's actually a good 
>> thing. The only thing worse than not enough information is too much 
>> information, and the current situation does a good job of discouraging 
>> the sorts of people who submit bad bug reports (e.g. duplicates of bug 
>> reports, bug reports for things fixed years ago, bug reports that are due 
>> to mistakes in their code, etc.).
> 
> Stephen, Alex, etc.: have you actually used the php.net doc system?
> Don't knock it til you've tried it.  IMO it is superior to Python's
> system.  I don't use PHP much these days.

I have to use PHP from time to time, in which cases I often have to use
the manual on php.net. I don't like it at all.

The official documentation is often incomplete, leaving out the details
I need and forcing me to read the comments.

Which I don't want to do, since many comments show a lack of
understanding of the subject matter. I have to read all of them, trying
to find out which ones are correct and which ones are wrong (or
misleading) to get the complete picture.


I like Python's documentation, where I can be confident that the
documentation is correct (except in the case of the very exceptional
bug) and mostly clear, much better.

-- 
The saddest aspect of life right now is that science gathers knowledge
faster than society gathers wisdom.
  -- Isaac Asimov

Roel Schroeven



More information about the Python-list mailing list