On Mon, Jul 9, 2012 at 10:57 AM, Steven D'Aprano <steve+comp.lang.pyt...@pearwood.info> wrote: > On Mon, 09 Jul 2012 07:54:47 +1000, Chris Angelico wrote: > >> It's like >> the difference between reminder text on a Magic: The Gathering card and >> the actual entries in the Comprehensive Rules. Perfect example is the >> "Madness" ability - the reminder text explains the ability, but uses >> language that actually is quite incorrect. It's a better explanation, >> though. > > Hang on, you say that an explanation which is "quite incorrect" is > *better* than one which is correct? > > I can see why they call the card "Madness". > > :-P
Agreed about the ability name :) The fact is, though, that when you're explaining something, it's often better to have a one-sentence explanation that's not quite technically accurate than two paragraphs explaining it in multiple steps and are opaque to anyone who doesn't have the rules-lawyer mind. (I happen to have such a mind. It's not always a good thing, but it makes me a better debugger.) Does it really hurt to anthropomorphize and say that "Python looks for modules in the directories in sys.path" instead of "Module lookup consists of iterating over the elements in sys.path [and that's leaving out the worst-case DFS where you explain THAT in detail], calling combine_path [or whatever it is] with the element and the module name, and attempting to stat/open the result"? While your listener's getting bogged down in unnecessary detail, s/he isn't grokking the overall purpose of what you're saying. One option is more accurate. The other is far more helpful. ChrisA -- http://mail.python.org/mailman/listinfo/python-list
