opinion: comp lang docs style

[rurpy at yahoo.com]

On 01/04/2011 11:29 PM, Steven D'Aprano wrote:
> On Tue, 04 Jan 2011 15:17:37 -0800, rurpy at 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.)