[docs] Bug / Room for Improvement

[Georg Brandl]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Am 10.09.2013 15:21, schrieb 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.

Hi Sterling,

I understand your concerns completely; the whole "Classes" tutorial has grown to
be an unwieldy mixture of tutorial and reference (myself I think that "nonlocal"
has no place in a tutorial for beginners anyway), and should be rewritten from
start; unfortunately that is quite a big (and ungrateful) job for volunteer
work.

I've at least fixed your first issue, the problem was that the newline in the
method definition as shown tells the interactive interpreter that the method
definition is finished; this would not happen in source files.  I've removed
the newline from the example now so that it can be pasted more easily in
interactive mode.

cheers,
Georg



-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.21 (GNU/Linux)

iEYEARECAAYFAlJRFTgACgkQN9GcIYhpnLCChQCfe89hah5n4YaPqkYpgf0hKGqR
9x8AmwbikisU1NiL9UVcTrTA2RTwG8jA
=mNzz
-----END PGP SIGNATURE-----