Python docs disappointing - group effort to hire writers?
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
More information about the Python-list