On Nov 17, 11:10 am, "Francesco Guerrieri" <[EMAIL PROTECTED]> wrote: > On Mon, Nov 17, 2008 at 6:44 PM, <[EMAIL PROTECTED]> wrote: >> On Nov 17, 8:54 am, "Gabriel Genellina" <[EMAIL PROTECTED]> >> wrote: >>> Candidate to *Longest and Most Boring Thread of the Year* - started >>> more than a month ago, currently discussing "The official definition >>> of call-by-value", and "What't the value of an object": >>> http://groups.google.com/group/comp.lang.python/t/6163956596a8c082/ >> >> Nice. The Python Reference defines objects, the core concept >> of Python, as id, type, and value, and then leaves one clueless >> about what a value is, and several notable Python contributors >> declare the subject boring. >> >> I guess this goes a long way to explaining why the Python docs >> suck so badly in many areas. > > This is a commonly heard assertion. > Maybe it's just me but I find that on average Python documentation on > the web is pretty good (*) and does its job very well.
"Good" is a subjective word. And actually I too think they are pretty good, at least relative to the quality of many free software projects. But Python is a very high quality language (albeit with a few quirks) and the quality of the docs really doesn't rise to the quality of the language. The discussion here and in part of the longest most boring thread was caused by the lack of a decent description of Python objects. The 2.6 docs say coverage of new-style classes is still incomplete although it appears better than in 2.5. Besides missing information much text appears to have been written by people in a contest to see who could describe something in the fewest possible words and still defend it as arguably correct. One really needs to keep the end goal in mind -- transmittal of the information to the reader. The organization is still bizarre, with the *builtin* types and functions documented in the Library(!) manual rather that Language Manual where one would expect them (in that I hardly think you could have a Python language implementation without a int type or a list type.) One would think the Library Manual would describe the modules that were not-essential to the core Python. And then there are lots of little things like the comment in the description of the packages in import statement: "XXX: Can't be bothered to spell this out right now", with a url to a description of packages in Python 1.5. (From the Python 2.5 docs, haven't installed 2.6 yet.) How would you feel if you bought a book and read that in it? But to see the difference between the Python Docs and "good" documentation, take a look at something like David Beasley's "Essential Python". It is not perfect either of course (among other things it copies nearly verbatim the incomplete Python Doc definition of "object") and it is not intended to define the language, but the organization and clarity of writing is way better than the Python Docs. When you look at the the details of the individual modules, there is a nearly infinite list of minor to moderate problems. All that being said, the docs are slowly getting better over time, and the people working on them certainly deserve thanks and appreciation for the hard work that has gone into them. > One is also left to wonder why all these critics don't take some > initiative and work to improve it. What makes you think that all of them don't? -- http://mail.python.org/mailman/listinfo/python-list
