Message154051
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 |
|
Date |
User |
Action |
Args |
2012-02-23 05:37:53 | ezio.melotti | set | recipients:
+ ezio.melotti, terry.reedy, eric.araujo, eli.bendersky, docs@python |
2012-02-23 05:37:53 | ezio.melotti | set | messageid: <1329975473.84.0.795852636525.issue14097@psf.upfronthosting.co.za> |
2012-02-23 05:37:53 | ezio.melotti | link | issue14097 messages |
2012-02-23 05:37:52 | ezio.melotti | create | |
|