Python documentation too difficult for beginners

Kee Nethery kee at kagi.com
Wed Nov 3 01:43:24 CET 2010


> 
>> 
>> Therefore, if you truly want changes in the documentation, I suggest that,
>> rather then whining to the group, you make some of the changes yourself.
> 
> I agree up to here, with a different interpretation of the last clause.
> Work within the existing system. There are currently 250 open doc issues on the tracker at bugs.python.org.

wow, a backlog of 250. Either 250 is the weekly submittal amount and they get dealt with within a week, OR the backlog is months old and the bug system is not an effective way to get changes or enhancements to the documentation. Either way, 250 open doc issues gives me the feeling that the existing documentation system is not working for the people trying to use it.

> After registering, go to the search page
> http://bugs.python.org/issue?@template=search&status=1
> select Components: Documentation and hit Return (or [Search])
> 
> Find an issue that is waiting for someone to suggest a new or replacement sentence or paragraph, and make one. No .diff patch required, just put it in the message. Or look at existing suggestions and comment.

Given that newbies are the ones who run into these issues and have a great desire to spare others the pain they have suffered trying to learn Python, and newbies typically do not know about the bug tracking system as the way to request enhancements to the docs (that's not how wikipedia and other sites do changes to information), perhaps it would be useful to put a link to a page that explains how to improve the docs, on each doc page? 

I have to agree with others. My preferred Python documentation is either the books I have, or a search on Google. A google search typically has several postings from people on non-official sites with the exact same confusion I have, and what they have tried and what ultimately worked. The suggestion was made that people create their own documentation if they don't like the official documentation, and that does seem to be a good source for python documentation.

Kee Nethery





More information about the Python-list mailing list