opinion: comp lang docs style

[rurpy at yahoo.com]

On 01/04/2011 01:34 PM, Terry Reedy wrote:
> On 1/4/2011 1:24 PM, an Arrogant Ignoramus wrote:
>
> what he called
>> a opinion piece.
>
> I normally do not respond to trolls, but while expressing his opinions,
> AI made statements that are factually wrong at least as regards Python
> and its practitioners.

Given that most trolls include factually false statements,
the above is inconsistent.  And speaking of arrogant, it
is just that to go around screaming "troll" about a posting
relevant to the newsgroup it was posted in because you don't
happen to agree with its content.  In doing so you lower
your own credibility.  (Which is also not helped by your
"Arrogant Ignoramus" name-calling.)

> [...]
> 2. AI also claims that this notation is 'incomprehensible'.

Since incomprehensibility is clearly subjective your claim
that it is a factual error is every bit as hyperbolic as his.

> [...]
> 3. AI's complaint is deceptive and deficient in omitting any mention the
> part of the docs *intended* to teach beginners: the Tutorial. The main
> doc pages list the Tutorial first, as what one should start with. That
> [...]
> 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.

The difficulty of doing that is a measure of the failure of the
python docs to achive a level quality commensurate with the language
itself.

FWIW, I think the BNF in the LR is perfectly reasonable given the
target audience I gave above.  The failure of the LR has more to
do with missing or excessively terse material -- it concentrates
too exclusively on syntax and insufficiently on semantics.  Much
of the relevant semantics information is currently mislocated in
the SLR.