<div dir="ltr">Hello,<div><br></div><div>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 ":"</div>
<div><br></div><div>The part where your documentation addresses this is the third paragraph down like so:</div><div><br></div><div><span style="color:rgb(0,0,0);font-family:sans-serif;font-size:16px;line-height:20px;text-align:justify">Dictionaries can be created by placing a comma-separated list of </span><tt class="" style="background-color:rgb(236,240,243);padding:0px 1px;font-size:0.95em;color:rgb(0,0,0);line-height:20px;text-align:justify"><span class="">key:</span> <span class="">value</span></tt><span style="color:rgb(0,0,0);font-family:sans-serif;font-size:16px;line-height:20px;text-align:justify"> pairs within braces, for example: </span><tt class="" style="background-color:rgb(236,240,243);padding:0px 1px;font-size:0.95em;color:rgb(0,0,0);line-height:20px;text-align:justify"><span class="">{'jack':</span> <span class="">4098,</span> <span class="">'sjoerd':</span> <span class="">4127}</span></tt><span style="color:rgb(0,0,0);font-family:sans-serif;font-size:16px;line-height:20px;text-align:justify"> or</span><tt class="" style="background-color:rgb(236,240,243);padding:0px 1px;font-size:0.95em;color:rgb(0,0,0);line-height:20px;text-align:justify"><span class="">{4098:</span> <span class="">'jack',</span> <span class="">4127:</span> <span class="">'sjoerd'}</span></tt><span style="color:rgb(0,0,0);font-family:sans-serif;font-size:16px;line-height:20px;text-align:justify">, or by the </span><a class="" href="http://docs.python.org/2.7/library/stdtypes.html#dict" title="dict" style="color:rgb(53,95,124);text-decoration:none;font-family:sans-serif;font-size:16px;line-height:20px;text-align:justify"><tt class="" style="background-color:transparent;padding:0px 1px;font-size:0.95em;font-weight:bold"><span class="">dict</span></tt></a><span style="color:rgb(0,0,0);font-family:sans-serif;font-size:16px;line-height:20px;text-align:justify"> constructor.</span></div>
<div><br></div><div>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.<br>
</div><div><br></div><div>Thanks for taking the time to read through my criticism. I really appreciate everything you guys are doing.</div><div><br></div><div>-Elizabeth Kehler</div></div>