Title: Improve the "introduction" page of the tutorial
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 2.7
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: akuchling, andymaier, chris.jerdonek, docs@python, eric.araujo, ezio.melotti, georg.brandl, python-dev, r.david.murray, rhettinger, terry.reedy, tshepang, zach.ware
Priority: normal Keywords: patch

Created on 2012-02-23 05:37 by ezio.melotti, last changed 2014-07-02 16:27 by zach.ware. This issue is now closed.

File name Uploaded Description Edit
issue14097.diff ezio.melotti, 2012-02-24 07:00 Patch against 2.7.
issue14097-1.diff ezio.melotti, 2012-11-26 16:01 Work in progress patch against 3.2. review
issue14097-2.diff ezio.melotti, 2013-04-01 23:07 Patch against 3.3. review
issue14097-3.diff ezio.melotti, 2013-05-19 17:08 review
issue14097-2.7.diff zach.ware, 2014-05-30 18:22 Backport of 796d1371605d and subsequent changes review
Messages (31)
msg154051 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-02-23 05:37
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.

msg154092 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-02-23 21:29
some of theses are great suggestions.  I'll do an update shortly.
msg154117 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-02-24 07:00
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).
msg154118 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-02-24 07:13
msg154156 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-02-24 20:30
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:



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.
msg154159 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-02-24 20:45
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
msg154192 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-25 06:59
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).
msg154201 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-02-25 08:00
> 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").

-   >>> 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;
 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;
msg154315 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-02-26 08:49
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.
msg154381 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-02-26 20:24
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'.
msg154382 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-02-26 20:32
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.
msg154400 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-02-26 21:52
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.
msg176423 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-26 16:01
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.
msg185781 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-04-01 23:07
Attached a new patch that should address all the points except the last example with Fibonacci.
msg188216 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-05-01 12:44
If there aren't any comments I will commit this soon.
msg188232 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-05-01 16:31
Review comments added.
msg189606 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-05-19 17:08
Here is an updated patch.
msg189607 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2013-05-19 17:24
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.
msg189608 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-05-19 17:44
> 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 ( ;);

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.
msg189631 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2013-05-20 02:15
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.
msg189633 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-05-20 02:27
Is it OK if I add it back to the next page, when I explain object identity?
msg189634 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2013-05-20 02:30
> Is it OK if I add it back to the next page, 
> when I explain object identity?

Yes.  That would work.
msg189638 - (view) Author: Roundup Robot (python-dev) Date: 2013-05-20 05:14
New changeset 796d1371605d by Ezio Melotti in branch '3.3':
#14097: improve the "introduction" page of the tutorial.

New changeset 42dda22a6f8c by Ezio Melotti in branch 'default':
#14097: merge with 3.3.
msg192665 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-07-08 15:56
This still needs to be backported to 2.7.  There's also a typo reported in #18403 that should be fixed before the backport.
msg219409 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2014-05-30 18:22
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.
msg222051 - (view) Author: Andy Maier (andymaier) * Date: 2014-07-01 17:43
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.
msg222056 - (view) Author: Roundup Robot (python-dev) Date: 2014-07-01 19:31
New changeset 438da6ae38fa by Zachary Ware in branch '2.7':
Issue #14097: Backport 796d1371605d and subsequent changes.
msg222057 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2014-07-01 19:37
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.
msg222071 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2014-07-02 05:40
Thanks for backporting this!
msg222112 - (view) Author: Andy Maier (andymaier) * Date: 2014-07-02 16:19
> 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...)

msg222113 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2014-07-02 16:27
You're both welcome :)
Date User Action Args
2014-07-02 16:27:46zach.waresetmessages: + msg222113
2014-07-02 16:19:00andymaiersetmessages: + msg222112
2014-07-02 05:40:36ezio.melottisetmessages: + msg222071
2014-07-01 19:37:45zach.waresetstatus: open -> closed
resolution: fixed
messages: + msg222057

stage: patch review -> resolved
2014-07-01 19:31:12python-devsetmessages: + msg222056
2014-07-01 17:43:43andymaiersetnosy: + andymaier
messages: + msg222051
2014-05-30 18:22:47zach.waresetfiles: + issue14097-2.7.diff

stage: commit review -> patch review
messages: + msg219409
versions: - Python 3.3, Python 3.4
2014-05-29 19:36:02zach.waresetnosy: + zach.ware
2013-07-08 15:56:14ezio.melottisetassignee: docs@python -> ezio.melotti
messages: + msg192665
2013-05-20 05:14:26python-devsetnosy: + python-dev
messages: + msg189638
2013-05-20 02:30:48rhettingersetmessages: + msg189634
2013-05-20 02:27:23ezio.melottisetmessages: + msg189633
2013-05-20 02:15:31rhettingersetmessages: + msg189631
2013-05-19 17:44:26ezio.melottisetmessages: + msg189608
2013-05-19 17:24:09rhettingersetmessages: + msg189607
2013-05-19 17:08:37ezio.melottisetfiles: + issue14097-3.diff

messages: + msg189606
2013-05-11 20:06:53ezio.melottisetnosy: + akuchling
2013-05-01 16:31:15r.david.murraysetnosy: + r.david.murray
messages: + msg188232
2013-05-01 12:44:50ezio.melottisetmessages: + msg188216
stage: patch review -> commit review
2013-04-01 23:07:09ezio.melottisetfiles: + issue14097-2.diff

stage: needs patch -> patch review
messages: + msg185781
versions: - Python 3.2
2012-11-26 16:01:24ezio.melottisetfiles: + issue14097-1.diff

messages: + msg176423
2012-09-26 16:51:37ezio.melottisetnosy: + chris.jerdonek

versions: + Python 3.4
2012-06-08 12:38:16eli.benderskysetnosy: - eli.bendersky
2012-02-26 21:52:43georg.brandlsetnosy: + georg.brandl
messages: + msg154400
2012-02-26 20:32:36terry.reedysetmessages: + msg154382
2012-02-26 20:24:37terry.reedysetmessages: + msg154381
2012-02-26 08:49:48eli.benderskysetmessages: + msg154315
2012-02-25 08:00:18ezio.melottisetmessages: + msg154201
2012-02-25 06:59:44eric.araujosetmessages: + msg154192
2012-02-24 20:45:39eli.benderskysetmessages: + msg154159
2012-02-24 20:30:08eli.benderskysetmessages: + msg154156
2012-02-24 19:58:49tshepangsetnosy: + tshepang
2012-02-24 07:13:49rhettingersetmessages: + msg154118
2012-02-24 07:00:45ezio.melottisetfiles: + issue14097.diff
assignee: rhettinger -> docs@python
messages: + msg154117

keywords: + patch
2012-02-23 21:29:31rhettingersetassignee: docs@python -> rhettinger

messages: + msg154092
nosy: + rhettinger
2012-02-23 05:37:53ezio.melotticreate