Here are some thoughts on reorganizing Python's documentation, with one big suggestion.
The tutorial seems to be in pretty good shape because Raymond Hettinger has been keeping it up to date. It doesn't cover everything, but it's a solid introduction, and if people don't find it works for them, they have lots of alternative books. No suggestions here. There are endless minor bugs in the library reference, but that seems unavoidable. It documents many different and shifting modules, and what to document is itself a contentious issue, so I don't think the stream of small problems will ever cease. There's another struggle within the LibRef: is it a reference or a tutorial? Does it list methods in alphabetical order so you can look them up, or does it list them in a pedagogically useful order? I think it has to be a reference; if each section were to be a tutorial, the manual would be huge. Here I think the solution is to encourage separate tutorials and HOWTOs, and link to them from the LibRef. The library reference has so many modules that the table of contents is very large. Again, not really a problem that we can fix; splitting it up into separate manuals doesn't seem like it would help. The Extending/Embedding manual isn't great, but only advanced users will come in contact with it, so I don't think it's a critical factor. (Michael Hudson's new manual is a promising replacement.) I suspect the Achilles' heel of the docs is the Language Reference. Put aside the fact that it's not up to date with new-style classes and other stuff; that would be fixable with some effort. To some degree, the guide is trying to be very formal; it's written like a specification for an implementor, not a document that people would read through. But there's no other way for people to learn about all the special object methods like __add__; the tutorial can't cover them all, and the LibRef doesn't describe them. So the newbie is stuck. For example, I noticed this passing reference in Tim Bray's weblog: http://www.tbray.org/ongoing/When/200x/2005/08/27/Ruby Based on first impressions and light exposure (a basis that matters a lot) Ruby seems better-documented and easier to get into than Python. I've actually written (a little) production code in Python, but I always had the feeling that there was lots of stuff going on I didn't understand; a couple of days in, I think I have a better grasp on what Ruby's up to, even where I'm not looking. I don't know exactly what Bray meant, but suspect that a more readable reference guide would have helped him understand what was going on. Perhaps we need a friendlier counterpart to the RefGuide, something like the 20-page introduction to Python at the beginning of Beazley's Essential Reference: * go over the statements one-by-one * go over the basic types and their methods * go over object semantics * cover some of the lexical material in chapter 2 of the RefGuide * overarching principles: go into a fair bit of detail, but not every corner case; make the text readable, not meticulously precise. (I should point out: this suggestion is not entirely different from some of the suggestions that X*h L** has made. He (?) makes his suggestions in a venomous style, and with his own eccentric terminology, but that doesn't mean he's always wrong, e.g. his complaints about the re module's documentation are well-placed in the main.) One problem with such a friendly document: it might make the Ref Guide even more irrelevant, if we always updated the friendly document (which is easy) and left the RefGuide to drift even further out of date (because it's hard to update). I don't know if this is an argument for not having a friendly guide, or for dumping the RefGuide entirely. Dumping the RefGuide means there isn't a more formal-style description of Python's semantics. I don't know if this matters. In theory, the implementors of Jython or IronPython could be using the RefGuide to know what they need to implement, but in practice I suspect implementors use the test suite and existing library as checks. Maybe we don't really need a tediously precise description of Python. What do people think? --amk -- http://mail.python.org/mailman/listinfo/python-list
