Python docs disappointing - group effort to hire writers?

alex23 wuwei23 at gmail.com
Thu Aug 6 17:52:51 CEST 2009


Kee Nethery wrote:
> As I struggle through trying to figure out how to make python do  
> simple stuff for me, I frequently generate samples. If some volunteer  
> here would point me towards the documentation that would tell me how I  
> can alter the existing Python docs to include sample code, I'd be more  
> than happy to do so.

No offence, but the last thing the official documentation needs is
example code written by people learning how to code. Suggest changes,
request clarifications, submit samples for review, sure, but direct
modification by users? I've seen the PHP docs; thanks but no thanks.

> I would like to "do it". Please point me to the docs that tell me how  
> to "do it" so that we people with newbie questions and a need for  
> examples can get out of your way and "do it" ourselves.

You start by reading this: http://docs.python.org/documenting/index.html
And this: http://www.python.org/dev/contributing/
And this: http://wiki.python.org/moin/WikiGuidelines

The first link, which directly answers your question, is clearly
listed on the doc contents page as "Documenting Python". I'm uncertain
how the docs could be made any _more_ helpful if people aren't
prepared to put effort into reading them. We're a long way away from
direct upload to the brain, unfortunately.

If you're learning the language, you should also consider using more
appropriate resources:
http://mail.python.org/mailman/listinfo/tutor
http://www.doughellmann.com/PyMOTW/
http://diveintopython.org/

The documentation cannot be all things to all people, and it most
certainly can't be a guide to general programming, which is what often
seems to be the issue with novice users. Python's a great language to
learn how to program in, sure, but I would hate to see that become the
focus of the docs.



More information about the Python-list mailing list