[docs] [issue14097] Improve the "introduction" page of the tutorial
Ezio Melotti
report at bugs.python.org
Thu Feb 23 06:37:53 CET 2012
New submission from Ezio Melotti <ezio.melotti at 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 at python
components: Documentation
messages: 154051
nosy: docs at 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 at bugs.python.org>
<http://bugs.python.org/issue14097>
_______________________________________
More information about the docs
mailing list