This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author ezio.melotti
Recipients docs@python, eli.bendersky, eric.araujo, ezio.melotti, terry.reedy
Date 2012-02-23.05:37:52
SpamBayes Score 5.726475e-12
Marked as misclassified No
Message-id <1329975473.84.0.795852636525.issue14097@psf.upfronthosting.co.za>
In-reply-to
Content
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
History
Date User Action Args
2012-02-23 05:37:53ezio.melottisetrecipients: + ezio.melotti, terry.reedy, eric.araujo, eli.bendersky, docs@python
2012-02-23 05:37:53ezio.melottisetmessageid: <1329975473.84.0.795852636525.issue14097@psf.upfronthosting.co.za>
2012-02-23 05:37:53ezio.melottilinkissue14097 messages
2012-02-23 05:37:52ezio.melotticreate