On 01/04/2011 11:29 PM, Steven D'Aprano wrote: > 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.
Yes it should. That's not what the tutorial is for. The (any) tutorial is for people new to python, often new to programming, who have the time and a learning style suitable for sitting down and going through a slow step-by-step exposition, much as one would get in a classroom. That is a perfectly valid way for someone in that target audience to learn python. Your (and Terry's) mistake is to presume that it is appropriate for everyone, perhaps because it worked for you personally. There is a large class of potential python users for whom a tutorial is highly suboptimal -- people who have some significant programming experience, who don't have the time or patience required to go through it getting information serially bit by bit, or whos learning style is, "don't spoon feed me, just tell me concisely what python does", who fill in gaps on a need-to-know basis rather than linearly. I (and many others) don't need or want an explanation of how to use lists as a stack! A language reference manual should completely and accurately describe the language it documents. (That seems fairly obvious to me although there will be differing opinions of how precise one needs to be, etc.) Once it meets that minimum standard, it's quality is defined by how effectively it transfers that information to its target audience. A good reference manual meets the learning needs of the target audience above admirably. I learned Perl (reputedly more difficult to learn than Python) from the Perl manpages and used it for many many years before I ever bought a Perl book. I learned C mostly from Harbison and Steele's "C: A Reference". Despite several attempts at python using its reference docs, I never got a handle on it until I forked out money for Beazley's book. There is obviously nothing inherently "difficult" about python -- it's just that python's reference docs are written for people who already know python. Since limiting their scope that narrowly is not necessary, as other languages show, it is fair to say that python's reference docs are poorer. > 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. I defined (roughly) the target audience I was talking about when I wrote "for a programmer with a basic understanding of computers and some other programming languages". Let's dispense with the 6th-grade arguments about people who don't know how to read, etc. > 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. As I hope I clarified above, that was exactly my point too. There is a significant, unsatisfied gap between the audience that a tutorial aims at, and the audience that the reference docs as currently written seem to be aimed at. Since other language manuals incorporate this gap audience more or less sucessfully in their reference manuals, python's failure to do so is justification for calling them poor. (Of course they are poor in lots of other ways too but my original response was prompted by the erroneous claim that good (in my sense above) reference manuals were unnecessary because a tutorial exists.) -- http://mail.python.org/mailman/listinfo/python-list
