On Thu, 22 Jul 2010 22:24:39 -0700, march wrote: > Steven, thank you for your reply. > > It is true that I didn't read the document with enough carefulness. some > of my questions are answered in the page I post the link of. Some are > not. > But the documentation is poor. You need to read throughout the entire > page, hoping to find what you need about one single API, and you might > fail.
Of course the documentation can be improved. Nobody thinks it is perfect. But the Python documentation is actually pretty good compared to a lot of things out there. Perhaps you're spoilt from reading first class documentation and haven't had to struggle with fifteenth class documentation. > I don't think "Python is a volunteer effort" can justify the poor > documentation. Linux, glibc are based on volunteer effort too, and they > has good documentations. You missed my point. Python is a volunteer effort. If you think the documentation is poor, what are YOU doing to fix that, apart from complaining? We welcome patches to the documentation. If you don't know how to write a patch file, that's okay too. What suggestions do you have for fixing the docs? If people agree that your suggestions are good, *and* they care enough to make the effort, then somebody *might* generate a bug report for it, which eventually *might* lead to somebody producing a patch. But if you want to increase the chances, you need to be active and not just an armchair critic. Write the patch. If you can't write the patch, at least raise a bug report with a suggestion for fixing it. > I am not blaming those volunteers who devote their precious time to this > language. It will be good if the python communities get more people who > like to write documentation. Volunteers are welcome. The first step is to suggest an improvement to the docs, not just complain that they're not good enough. How would you fix the docs for socket.recv? -- Steven -- http://mail.python.org/mailman/listinfo/python-list
