[docs] Possible dictionary documentation improvement

[Elizabeth Kehler]

Hello,

I have been trying to learn python from the documentation, and until
recently I had no idea how to use dictionaries. Until someone told me in
plain english that dictionaries are collections of entries which you use to
look up a value from a unique key of your choosing, I couldn't make heads
or tails of your documentation. Mostly what I needed to know was that an
entry had the form {key:value} and that more entries could be added by
separating by commas like {key1:value1, key2:value2} and that "=" can be
used instead of ":"

The part where your documentation addresses this is the third paragraph
down like so:

Dictionaries can be created by placing a comma-separated list of key:
value pairs
within braces, for example: {'jack': 4098, 'sjoerd': 4127} or{4098: 'jack',
4127: 'sjoerd'}, or by the
dict<http://docs.python.org/2.7/library/stdtypes.html#dict>
 constructor.

Reading your documentation now with the above knowledge it makes perfect
sense, but when I was new to it, I didn't get the information I needed. I
stongly advise rewording this documentation by adding a paragraph at the
beginning talking about how dictionaries are used in plain english, and
stating that the key comes first and the value second in each entry without
saying that you "can" do it that way. To someone new, the word "can" sounds
like you are introducing a nonstandard way of doing things that might be
interesting to someone who already knows what is going on, but not very
useful in figuring out how these things actually work.

Thanks for taking the time to read through my criticism. I really
appreciate everything you guys are doing.

-Elizabeth Kehler
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20131219/af0e942e/attachment-0001.html>