I was reading the "introduction" page of the tutorial [0], and noticed a few things that could be improved:
 1) the first paragraph is a bit confusing, showing a simple example and explaining what the >>> is would be better;
 2) comments can be introduced later too, they are not really necessary at the beginning;
 3) the first example is supposed to introduce numbers and basic operations, but it's still going on with the comments;
 4) the note about floating point issues is not so relevant anymore nowadays, so it could be (re)moved;
 5) "A value can be assigned to several variables simultaneously:" is not technically correct;
 6) "Variables must be “defined” (assigned a value) before they can be used" this might be improved too;
 7) almost half of the section about numbers goes on explaining complex numbers.  This is totally unnecessary here, I think that mentioning them and maybe showing a simple example is more than enough.  Another option is to make a subsection with a note that says that the section can be skipped;
 8) the examples in this part lack some space (e.g. "a=3.0+4.0j");
 9) the print() function could get a better introduction and used in the first set of string examples;
 10) suggesting to use continuation lines with a trailing \ in string literals is not a good idea, it's better to use """...""" or implicit concatenation inside ();
 11) "Degenerate slice indices are handled gracefully" it might be better to show that it's not the same for "non-slice" indices;
 12) the "About Unicode" section could link to the Unicode HOWTO;
 13) while it's true that lists can contain different types of object, they usually shouldn't;
 14) while the "while" example is good (it first shows a piece of code and then explains what it does), I would introduce the "if" and the "for" first.  The "while" is arguably the most complex and less used of the three statements.

[0]: http://docs.python.org/py3k/tutorial/introduction.html

some of theses are great suggestions.  I'll do an update shortly.

The attached patch addresses 8) -- you might want to use it as a starting point (that's what I was going to fix before deciding to do a full review of the page).

Thanks.

Ezio, your fix for 8 is definitely good. Space makes it cleaner, as well as compliant to PEP 8, which explicitly recommends to surround operators with spaces.

Note, however, that this should be applied in other places as well, not only the complex number samples. For example:

2+2
(50-5*6)/4

etc.

There's quite a bit of inconsistency in the samples. Some surround operators with spaces and some don't. I think converging on a single consistent, PEP 8 compliant convention of surrounding with spaces always throughout the tutorial is a good idea.

Comments on some of the suggestions:

1) Agreed
2) Can be combined with (3), I think. Just show the number example with the explanatory comments. They speak for themselves. No need for the SPAM and STRING assignments.
5) Yep. Can be replaced by "A value can be assigned to several variables in a single statement"
6) There's the tradeoff of rigor vs. simplicity here, since this is still a tutorial for beginners, right? What alternative would you propose?
7) Totally agree. I don't think complex numbers deserve more than a single trivial example and one sentence dedicated to them in the tutorial, if that...
8) Yes. See my previous message in this issue
9) "It differs from just writing the expression you want to write" is definitely confusing
10) Agree
11) This is kind-of mentioned later in the negative index part. It may be worth mentioning that a single index must be within bounds, but the explanation on degenerate slices has its place too, since it's a friendly feature of Python many rely on.
12) Agree
13) This is probably too arguable to be included. With Python's duck typing there *is* sometimes place for placing different objects in the same list, with the understanding that they all have some common behavior (for example, callables).
14) Agree

Be careful with whitespace changes.  Sometimes not putting whitespace around an operator helps to see the grouping of operations, for example.  The important thing is “Readability counts”, not “Always put whitespace around operators”.  A huge part of understanding PEP 8 is to know when not to follow PEP 8 (PEP 20 is not called a Zen for no reason :)

About 5)-6): I really wish the docs wouldn’t use the term “variable”, which means something else in most other programming languages and always cause beginners to stumble upon unexpected-for-them binding behavior.

A remark that’s probably culture-dependent: “degenerate” nearly sounds like a racist insult to me (see 11).

> Be careful with whitespace changes.

Here I agree with you and disagree with the PEP 8 (specifically where it says that "hypot2 = x*x + y*y" and "c = (a+b) * (a-b)" are "wrong").

In
-   >>> 3+1j*3
+   >>> 3 + 1j * 3
I intentionally added spaces around all the operators to leave the expression ambiguous.  IIUC the point of that example is to show that even if 3+1j is a single entity, normal precedence rules still apply, so I didn't want the reader to make any assumptions about the precedence based on the whitespace (or even worse thing that the whitespace might define the precedence).

Additional comments and replies about the list:
 1) A user was confused about >>>, thought that was necessary to "define variables", that you had to always include it in your code.  The tutorial should make clear that this is used only in the interactive interpreter and not in regular code;
 2-3) what Eli said sounds good to me;
 5) "A value can be assigned to several variables simultaneously:" might lead to thing that "a = b = []" is the same as "a = []; b= []".  The term "variable" has a different meaning in other languages, but that doesn't mean we should refrain to use it -- we just have to specify what we mean with "variable" (this can be done later, saying that "both a and b will refer to the same list" should be enough here);
 6) here the idea is that is not the value to be assigned to the variable (like in C where the vars are like boxes and you can put values inside), but the variable that is used to refer to the object (so it's more like a label assigned to the object).  Again we can don't need to be too specific here yet, but we shouldn't say wrong things either.  See also http://python.net/crew/mwh/hacks/objectthink.html;
 11) presenting the error raised with the index first and the fact that slices are more "permissive" later sounds better to me;
 13) I'm not saying we should specifically tell users to put object of the same kind in a list, but just to avoid focusing on this aspect and use "realistic" examples.  Adding a note at the end saying that "lists can also contain objects of different types" should be enough;

Regarding the use of the name "variable", could it be replaced by just "name" ? That might make sense since the error for undefined "names" is usually NameError. However, note that the current documentation has a /huge/ amount of mentions for "variable", so we may be too late to the party.

Éric - the word "degenerate" is considered offensive in a couple of languages I speak, but the docs are written in English, so the important point is whether this word is offensive *in English*. If not, I see no reason to drop it.

In English, calling someone or something 'degenerate' is a major insult. In means that x is not really human or what it seems or what it was. I remember being initially startled or puzzled at the mathematical usage, but it actually is similar, just without the strong insult. A line is a degenerate parabola; a line segment is a degenerate ellipse; crossed lines constitute a degenerate hyperbola; a line segment and a point on the segment constitute a degenerate triangle. There are all limit cases, but they are simplified 'degenerated' limit cases that lack the curvature or dimensionality of the members of the sets that they are limits of. Note that straight lines are only degenerate as a limit of parabolas; they are fine figures in their only right.

0/0 as the limit of 0/x for small x is degenerate in that it looses the essential property of being a well defined real number.

'Degenerate' should not be casually applied to limits, edge cases, corner cases, or oddball cases in general. One could claim that empty counts and collections, including sequences, are 'degenerate' limits in that they loose the 'essential' property of somethingness. But if one means that, then they should be denied existence, as was done for 0 and empty sets, or put in separate classes. (For 0 and {}, there really is a sense of insult that does not apply to lines. We still see it with 'imaginary' numbers.) By including 0 and empty collections in their respective classes, Python denies that they are degenerate. So I do not think any slice should be called 'degenerate'. Certainly, the contrast between all slices working and only some indexes working has nothing to do with 'degeneracy'.

I think we should feel free to change 'variable' to 'name', especially in the Intro, if it can be done gracefully in context. In my experience with python-list, the former seems a source of confusion for Python newbies. I try to avoid it when writing about Python.

Well, I guess some people will always be blind to the finer distinctions in the scientific meaning of words...  but that doesn't mean we should apply them where they don't.

I started working on this.  Attached there's a work in progress patch with changes done on the first half of the tutorial.
The changes are not definitive, and I'm trying to get some early feedback on rietveld before moving on the second half.

Attached a new patch that should address all the points except the last example with Fibonacci.

If there aren't any comments I will commit this soon.

Review comments added.

Here is an updated patch.

Please restore the section "A value can be assigned to several variables simultaneously".  This is easy to teach in this context and there's no other good place to put it.

Also, I'm unclear why you took out the Mark Lemburg's section on Unicode.

> Please restore the section "A value can be assigned to several
> variables simultaneously".

The reason for removing it are:
 * generally it's not really useful/used IMHO;
 * it has potentially confusing side effects (e.g. x = y = 0 is the same as x = 0; y = 0, but a = b = [] is not the same as a = []; b = []);
 * and more confusing side effects (http://mail.python.org/pipermail/python-dev/2012-November/122552.html ;);

IOW I think that teaching this (especially at this point of the tutorial where you can't/shouldn't yet explain the side effects) does more harm than good.
It could be mentioned later in the tutorial when object identity is explained in more detail (I'm planning to work on this next), and should be also covered in the language reference (if it's not there already).

> Also, I'm unclear why you took out the Mark Lemburg's section
> on Unicode.

I'm planning to write something about Unicode when bytes are introduced.  That section has been written with Python 2 in mind, where byte strings are the default but "there are also Unicode strings".  For Python 3, users already naturally associate strings with text and explaining the text/bytes dichotomy and Unicode can be postponed.

Please add the "x = y = z = 0" example back.  It doesn't improve the tutorial to dumb it down or to leave out basic knowledge.  You may not like the feature but it is a long standing part of the core language.

Is it OK if I add it back to the next page, when I explain object identity?

> Is it OK if I add it back to the next page, 
> when I explain object identity?

Yes.  That would work.

New changeset 796d1371605d by Ezio Melotti in branch '3.3':
#14097: improve the "introduction" page of the tutorial.
http://hg.python.org/cpython/rev/796d1371605d

New changeset 42dda22a6f8c by Ezio Melotti in branch 'default':
#14097: merge with 3.3.
http://hg.python.org/cpython/rev/42dda22a6f8c

This still needs to be backported to 2.7.  There's also a typo reported in #18403 that should be fixed before the backport.

How's this for a 2.7 backport?  The least direct part of the backport is the section on division; I pretty much had to completely rewrite the paragraph in 2.x terms and I'm not certain that I took the best approach.

Zach, I reviewed your 2.7 backport, including a comparison with the latest 3.x patch.

Comments on the 2.7 backport:

1. In "3.1.1 Numbers", on "If both operands are ints,":
The "ints" is a link labeled "int" followed by a normal font "s". I think it would be better to avoid concatenating them, and to say something like: "If both operands are of type int,".

Comments on both the 2.7 backport and on the latest 3.x patch:

2. In the last paragraph of "3.1.1 Numbers" ("In addition to int and float, Python supports..:":
The long type could be mentioned here as well, only with a link and no explanation, consistent with how Decimal and Fraction are mentioned.

Comments on just the latest 3.x patch:

3. In "3.1.2. Strings", I am missing a mentioning that the characters in strings are Unicode characters. I think quite a bit of the unicode subclause of the 2.x patch would be appropriate. I would also mention byte strings at this point, but only the fact that they exist and with a link.

New changeset 438da6ae38fa by Zachary Ware in branch '2.7':
Issue #14097: Backport 796d1371605d and subsequent changes.
http://hg.python.org/cpython/rev/438da6ae38fa

Thanks for the reviews, Ezio and Andy.  Committed with most of your points addressed, though I did leave out the link to `long` since I could not come up with a good wording for adding it, and `long` is easily findable from `int`.  Also, the link for 'complex numbers' also explains `long`, so it should be easy to find without burdening newbies with another name that they may not need for some time.

Andy: in future, please use the 'review' link to post reviews, it makes it much easier for the patch author to keep track of where your comments are meant to apply, and you can leave comments on multiple versions of a patch if you like.

Thanks for backporting this!

> Andy: in future, please use the 'review' link to post reviews,...

Will do ... I just now discovered the "Start Review" link (I'm new here, so thanks for telling me...)

Andy

You're both welcome :)