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.

classification
Title: Use of dicts in 4.2 and 4.7 of Python tutorial a bit confusing
Type: Stage: resolved
Components: Documentation Versions: Python 3.9
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, jessevsilverman, rhettinger, terry.reedy
Priority: normal Keywords:

Created on 2021-01-28 15:56 by jessevsilverman, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Messages (4)
msg385870 - (view) Author: Jesse Silverman (jessevsilverman) Date: 2021-01-28 15:56
The Python tutorial was not my first introduction to Python, but I see things in sections 4.2 and 4.7 that likely would have confused me a lot if it was.

In 4.2 near the end, we have great advice about how to avoid problems with modifying a collection while iterating thru it.

Unfortunately, it both makes use of a dict despite not having introduced it before at all within the tutorial (I wasn't shocked because it was NOT my first introduction to Python) and in fact, the .items() method which is beautifully explained in section 5.6, which hasn't been read yet.

I got thru it a bit shakily, and in a reference, rather than an introductory tutorial, it is quite literally impossible to present everything in a strict sequence, but I would definitely have been thrown for a loop if it was actually my first introduction to Python.

All was good again until I got to section 4.7.2, where I was again glad I had previously consumed tutorial materials concerning dict.  There is a forward reference to:
https://docs.python.org/3.9/library/stdtypes.html#typesmapping

Which every Python programmer should undoubtedly be familiar with eventually, but "why not?" to the more novice-friendly:
https://docs.python.org/3.9/tutorial/datastructures.html#dictionaries

The forward reference from this section to tuples in section 5 of the tutorial suggests that this might have been appropriate as well.

The dict, the tuple and parameter passing are all very basic topics indeed, but I would have found 4.7 very rough going if I had no prior exposure to dict and tuple.

This isn't a complaint demanding a refund for the cost of the tutorial, so much as an indication of where I think true novices attempting to follow the tutorial in sequence would likely be thrown for a loop.  I understand there is a healthy ecosystem of free and paid introductory tutorial material for Python, as evidenced by the fact that I was only working thru the tutorial just now, having been referred to it as a pre-req for other material I will be moving on to soon.
msg385941 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-01-29 21:21
For 4.2, the point is the '.copy()' versus the 'active_users' copy.  I think a real beginner would, or should, ignore any other details not immediately familiar.  

4.7.2 Keyword arguments.  It is simply a fact that including the full discussion here requires the forward references.  I think splitting the discussion and moving this part somewhere later would be worse.  Some will not be able to "follow the tutorial in sequence".  It is not a novel.

I think you should close this.  It makes observations but does not have any concrete suggestions for improvements, and unlike your other posts, I don't see that it might lead to any.
msg385954 - (view) Author: Jesse Silverman (jessevsilverman) Date: 2021-01-29 22:11
Agreed with the exception that I'd like to review whether the forward reference to dict in the tutorial might be better suited to people working thru the tutorial than the current forward reference to the real docs.

I got to take a look at Eric Matthes' excellent "Python Crash Course".  He avoids this by treating function definitions only after introducing both tuples and dicts, rather than together with simple control flow within a function.  That would clearly be a re-org that is way out of scope of a bug report.

So, if someone compares the potential forward reference to the dict section of the tutorial rather than the current forward reference to the language reference in light of where the tutorial audience is expected to be at when reading this section, I am good with closing it.
msg386064 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-02-01 12:20
The link to https://docs.python.org/3.9/library/stdtypes.html#typesmapping
 isn't a forward reference. It is a link to the main docs which is entirely appropriate and likely the only way a beginner would find that section.

I concur with Terry that this should be closed.  I've no evidence of an actual user ever having been confused by this presentation.
History
Date User Action Args
2022-04-11 14:59:40adminsetgithub: 87222
2021-02-01 12:20:31rhettingersetstatus: open -> closed

nosy: + rhettinger
messages: + msg386064

resolution: rejected
stage: resolved
2021-01-29 22:11:49jessevsilvermansetmessages: + msg385954
2021-01-29 21:21:34terry.reedysetnosy: + terry.reedy

messages: + msg385941
title: Use of dicts in sections 4.2 and 4.7 of Python tutorial a bit confusing -> Use of dicts in 4.2 and 4.7 of Python tutorial a bit confusing
2021-01-28 15:56:59jessevsilvermancreate