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

2013-06-17 Thread 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 supp...@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
-- 
http://mail.python.org/mailman/listinfo/python-list


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

2013-06-17 Thread Joel Goldstick
On Mon, Jun 17, 2013 at 6:50 PM, Steven D'Aprano 
steve+comp.lang.pyt...@pearwood.info wrote:

 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 supp...@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.



I read the python docs.  I've gone through the tutorials.  If not the first
time, or the second, I get that Aha moment with additional reads.  Some
people say they learn better by other methods than reading.  In that case,
google like crazy because python has lots of pycon stuff online in video
form, and there is the google course.  and many others.  If people
interaction is what you need, find, and visit your local meetup or user
group.  Lots of places have them.  If you don't have one near you, maybe
you could start one so you would have local help and back and forth
(fourth?).  I think its great to read a question here and get a link for an
answer.  gives me somewhere to go explore more.  If you reject these ways
of learning for the single method of asking.. fix my code.  Then you will
never get good at this craft anyway.  Its not the answers that are
important, its discovering how to find the answers that is really
important.  The old give a man a fish, vs teach a man to fish truism




-- 
Joel Goldstick
http://joelgoldstick.com
-- 
http://mail.python.org/mailman/listinfo/python-list