On Tue, 04 Jan 2011 15:17:37 -0800, ru...@yahoo.com wrote: >> If one wants to critique the 'Python Docs', especially as regards to >> usefulness to beginners, one must start with the Tutorial; and if one >> wants to use if statements as an example, one must start with the >> above. > > No. The language reference (LR) and standard library reference (SLR) > must stand on their own merits. It is nice to have a good tutorial for > those who like that style of learning. But it should be possible for a > programmer with a basic understanding of computers and some other > programming languages to understand how to program in python without > referring to tutorials, explanatory websites, commercially published > books, the source code, etc.
No it shouldn't. That's what the tutorial is for. The language reference and standard library reference are there to be reference manuals, not to teach beginners Python. In any case, your assumption that any one documentation work should stand on its own merits is nonsense -- *nothing* stands alone. Everything builds on something else. Technical documentation is no different: it *must* assume some level of knowledge of its readers -- should it be aimed at Python experts, or average Python coders, or beginners, or beginners to programming, or at the very least is it allowed to assume that the reader already knows how to read? You can't satisfy all of these groups with one document, because their needs are different and in conflict. This is why you have different documentation -- tutorials and reference manuals and literate source code and help text are all aimed at different audiences. Expecting one document to be useful for all readers' needs is like expecting one data type to be useful for all programming tasks. Reasonable people might disagree on what a particular documentation work should target, and the best way to target it, but not on the need for different documentation for different targets. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
