[docs] Bug / Room for Improvement

[Sterling Robertson]

In section 9.2.1 of the tutorial, at
http://docs.python.org/3/tutorial/classes.html, the sample program does not
work.  The following is what happens when someone tries to type it in (I'm
using IDLE for Python 3.3.2):

 

>>> def scope_test():

                def do_local():

                                spam = "local spam"

                def do_nonlocal():

                                nonlocal spam

                                

SyntaxError: no binding for nonlocal 'spam' found

 

This needs to be corrected, especially when you consider the poor
explanations and lack of clarity throughout these tutorials and especially
this chapter.  I'm a professional programmer, and I'm still having a hard
time following your tutorials.

 

One of the biggest issues is that you're trying to put too much detail into
too few words.  Many different facts are being thrown at absolute beginners
all at once, with very little elaboration.  Many of the details you're
trying to describe are not fully explained, causing critical gaps of
information.  You should do one of two things:

 

1)      Expand your tutorials and elaborate more fully on what it is you're
trying to communicate, making sure that every detail is completely explained
and well-defined.

2)      Remove many of the details that you're getting sidetracked on, and
re-invest that amount of space in the tutorials to more clearly explaining
the parts of the language that are more central and important for a beginner
who is studying the language for the first time.

 

Furthermore section 9.2 is using unorthodox terminology with little or no
explanation, and it's not very well-written in general.  This section
appears to be trying to explain a concept in overly complicated,
"beat-around-the-bush" wording, and it's not even doing that very well.  It
should be re-written from the ground up, and it should either use more
standard terminology, or if unorthodox terminology is a necessity, provide a
more thorough explanation of what that terminology means.  Even for
professional programmers, it is very hard to read and follow.

 

Please understand that I am not trying to be overly negative or critical,
but I do believe someone needs to go through the tutorial and look it over
for things like this.  Remember that some of the people reading this have no
previous programming experience, and when it's already difficult for
professionals to follow, it would be almost impossible for them.  Thank you.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130910/deffbe74/attachment-0001.html>