Aahz wrote: > Here's a question that kind of gets to the heart of a lot of the > problem: where does ``print`` get documented? If we can come up with a > good process for answering that question, we can probably fix a lot of > other problems. (Note emphasis on the word "process".)
Good point; the language reference and the tutorial is the only place we currently keep this kind of documentation, and neither provides the kind of reference that new users need. I'd also note that the distinction between builtins and syntax isn't meaningful to a new user. So, for instance, that "exec" and "eval" are documented in very different places is confusing. And that the "print" statement and the "write" method are also differently placed. I think it would be very useful if there was reference (not just tutorial) documentation for all the syntax, special semantics like magic methods, and all the functions and objects in builtins. To a new user these are all the same thing. Even to an experienced users these are all about the same thing. I don't think such a document would be all that long or hard to write. On a usability note, I'd want every name a user might encounter to show up in an index or table of contents. Basically all the keywords, magic methods, exceptions, builtin functions, builtin types, and at least somewhere the methods of builtin types should also be available. -- http://mail.python.org/mailman/listinfo/python-list
