Mistake one: The infield fly rule
Imagine there is a group of you from work at a baseball game--you know, one of those team-building outings. Someone in the group is a non-American, say a Swede over on special assignment. Along about the third inning he says, "Oh I get it, if the fielder catches the ball before it hits the ground, the batter is out. Is that right?" The correct answer is "Hey, you've got it, let me buy you a beer."
But there will be an expert in the group who will feel compelled to explain the infield fly rule. "Well that is often the case but if there are runners on first and second and the batter hits a fly to the infield, then the batter is automatically out regardless of if the ball gets caught or not and the runners do not advance. The reason, of course, is to discourage the infielder from deliberately dropping the ball and then having force outs on all the bases."
Not only is it a buzz kill for the Swede (and anyone else in earshot) it is completely unnecessary. Who needs to know the infield fly rule? The batter? No, because no batter would ever hit a fly to the infield on purpose. The fielders? No, because their play is irrelevant; the batter is out regardless of what they do. The runners? No, they will not be allowed to advance.
So the only person who needs to know the infield fly rule is the umpire, and he can explain it to everyone on the occasional blue moon when it happens.
In many software applications, the computer is the umpire, and as long as it knows what it has to do, don't load down the user with overly technical explanations. Experts want their explanations to be complete and accurate, but user explanations just have to be viable. Agile development has the principle of JBGE "Just Barely Good Enough." An explanation just has to be complete enough and accurate enough to get the user to the desired end goal. In our example, the Swede's understanding of baseball was adequate to enjoy and understand the game he was watching.
Mistake two: Too many explanations
If there is more than one way to do something, the expert will explain them all. At most we typically only need two ways to do something: (1) the easy way to remember and (2) the expert shortcut. Think about getting directions. If you are not comfortable with a particular section of town, would you prefer directions that had only two turns and took you 2.5 miles or one that had seven turns but only took 1.9 miles? Probably the longer but easier. After a while, though, you would probably like to know the shorter way.
Mistake three: The most difficult explanation
My guitar teacher showed me a way to derive all of the naturally occurring chords in a scale on the Dobro (for the key of G). The really useful ones are G, Am, Bm, C. D, and Em. The last one is an F#minor with flatted 5th. This would be like having a group of guys named Al, Bill, Tom, Dave, Fred, and Throckmorton (how did HE get in?) For months I have tried to figure out why this anomaly occurs, this seemingly out of place chord. Today driving in to work I realized it is a D7, a great transitional chord and one that makes sense showing up with the others. (Like finding out Throckmorton is a nickname his great aunt gave him, his real name is Ted.)
But the instructor was right, it could also be called an F#minor with flatted 5th (or a F#dim for that matter). He let himself get distracted, I think, by the sequence of the notes and did not see it in the simpler context.
- Look for viable explanations.
- Limit the number of alternatives to one easy one and one expert shortcut.
- Give the simplest explanation. (See Occam's Razor.)
postscript: In verifying my link I could not help but catch this irony (click to enlarge):