New submission from Ezio Melotti <ezio.melotti@gmail.com>: 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 ---------- assignee: docs@python components: Documentation messages: 154051 nosy: docs@python, eli.bendersky, eric.araujo, ezio.melotti, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Improve the "introduction" page of the tutorial type: enhancement versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14097> _______________________________________