Problems with Python documentation [Re: Don't feed the troll...]

[Steven D'Aprano]

On Mon, 17 Jun 2013 07:41:54 -0700, rurpy wrote:

> On 06/17/2013 01:23 AM, Chris Angelico wrote:
>> On Mon, Jun 17, 2013 at 3:04 PM, Ferrous Cranus <support at superhost.gr>
>> wrote:
>>> The only thing i'm feeling guilty is that instead of reading help
>>> files and PEP's which seem too technical for me, i prefer the live
>>> help of an actual expert human being.
>> 
>> This is definitely a reason to feel guilty. You are asking people to
>> provide live help for free, rather than simply reading the
>> documentation.
> 
> It is NOT a matter of simply reading the documentation. I have posted
> here several times as have many others about some of the problems the
> documentation has, especially for people who don't already know Python.

This is very reasonable. And nobody -- well, at least not me, and 
probably not Chris -- expects that reading the documentation will 
suddenly cause the light to shine for every beginner who reads it. Often 
the official docs are written with an expected audience who already knows 
the language well.

But in context, Nikos has been programming Python long enough, and he's 
been told often enough, that his FIRST stop should be the documentation, 
and us second. Not what he does now, which is to make us his first, 
second, third, fourth, fifth, sixth, seventh and eighth stops.

(Are you paying attention Nikos?)

But speaking more generally, yes, you are right, the docs are not a 
panacea. If they were, mailing lists like this, and websites like 
StackOverflow, would not exist.




-- 
Steven