Why is dictionary.keys() a list and not a set?
cito at online.de
Fri Nov 25 10:35:37 CET 2005
As a general note, I think it would be good to place the exact
description in a footnote, since speaking about hashable objects,
__hash__ and __cmp__ will certainly frighten off newbies and make it
hard to read even for experienced users. The main text may lie/simplyfy
a little bit.
Or as Donald Knuth once recommended:
"Simplify. Lie, if it helps. You can add the correct details later on,
but it is essential to present the reader with something straightforward
to start off with. So don’t be afraid to bend the facts initially where
this leads to a useful simplification and then pay back the debt to
truth later by gradual elaborations."
However, since the Python docs are a reference and not a textbook or
manual, I think the debt should not be payed back "later", but
immediately in a footnote.
The docs already follow this principle very well, e.g.:
More information about the Python-list