Xah Lee wrote: > The "Language Reference" section (subtitled "for language > lawyers") needs to be replaced by human-readible descriptions of > Python's functions. For exapmle, in the style of official Java doc > (http://java.sun.com/j2se/1.4.2/docs/api/index.html).
Nope. The Java documentation you're referring to corresponds to the "Library Reference" in Python, which is a collection of human-readable descriptions of Python's functions (whether you like them or not). Meanwhile, the corresponding Java documentation for Python's "Language Reference" is this document collection: http://java.sun.com/docs/books/jls/second_edition/html/jTOC.doc.html You'll notice that it resembles the Python documentation rather strongly. I'm afraid that the "Computer Science Pretension" is necessary with that kind of documentation so that "language lawyers" - ie. people implementing compilers, runtimes, tools - don't create something that doesn't work with genuine specimens of the language. Now, I don't doubt that Python's documentation could be improved, and I'm willing to improve it (and have improved it in the past). I even ticked the box on some feedback form at EuroPython to say that I'm willing to write Python docs. In fact, I may start looking at the documentation tasks on the Wiki and seeing what I can contribute, possibly from stuff I've already written but which doesn't trivially slot into the documentation as it is today. And I don't disagree with you that the PythonInfo Wiki is a structural mess (I can never manage to navigate from the front page to the WebProgramming page, although I obviously know the name of the page and don't need to, but this isn't going to help someone who doesn't know that it's there), nor do I disagree with you that TeX isn't exactly the most accessible technology. However, I would recommend that in order to be taken more seriously you tone down the rhetoric, review the available documentation (including stuff like "Dive Into Python" http://www.diveintopython.org/) and note the actual purpose of that documentation (eg. language vs. library reference) before suggesting the replacement of one text with another that already exists. > (in this respect, similar to how wikipedia's texts drift into a form of > academic > esoterica whose educational value and readibility are greatly reduced > to the general public.) And here's an example of that rhetoric I referred to. Personally, I find Wikipedia very readable even for my increasingly shortening attention span, and some academics would presumably argue that Wikipedia has already crossed some kind of line of compromise between accessibility and thoroughness. If you want things like the 1707 Act of Union (http://en.wikipedia.org/wiki/Act_of_Union_1707) explained to you without "esoterica", perhaps that says more about you than it does about Wikipedia. Please note that I'm not labelling you as a troll. As far as I can tell, many of your ideas are fairly sound; it's just that it's hard work to see past the rhetoric and posturing, which is a shame because you quite possibly have a lot to contribute. Paul -- http://mail.python.org/mailman/listinfo/python-list