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.
Conclusion
- 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):
6 comments:
Great post. I have just such a SME in my organization. Ask for a drink of information and she turns on the fire hose.
Looking forward to reading more of your thoughts. I am also a technical communicator by day and a musician and songwriter.
Best,
Dave H.
I must respectfully disagree. I do agree with the principle of simplicity in communication, but I think you take it a bit too far, as tech writers often do. Yes, when you communicate a concept, you should make that communication as simple as possible — but no simpler.
What's too simple? When you dodge difficult issues with the excuse "they don't need to know that." No, it's not always an excuse, but it often is.
For example: your Swedish friend does need to know about the IFR. Really. Not in painful detail, of course, but just enough to get by. Suppose that shortly after your conversation, the umpire invokes the rule. You're then caught in an obvious untruth. Your decision to oversimplify the fly ball concept then creates confusion and distrust. Probably not a big deal in a casual ball game, but very much so in technical communication.
Here's what I would tell the Swede: "Good! You've got it right, except for the infield fly rule. What's that? Don't worry about it, we'll explain it to you if it comes up."
OK, maybe your version is better when it's just a bunch of friends having fun, and the visitor will probably never play baseball again. (And might even be playing without an umpire, which makes the IFR unenforcable.) But in a technical document, the stakes are a bit higher.
Another thing: the "too much information" bit is only a mistake when a tech writer does it. It is definitely not a mistake when the expert does it. Your job as a tech writer is to filter out the cruft, not expect your SME to do it for you. It's a mistake on the writer's part (one I've made, and come to regret) to try to curb an SME in full babble mode. Not only do you risk missing a fact you didn't know you needed, but you're also trying to impose a concise mode of discussion on somebody who's probably not very good at it. The best you can do is to listen with as much patience as you can muster and try to keep the explanations more or less on-topic.
Spoken like a true expert, Isaac :-)
Great article, Mike. The baseball analogy is spot on -- and very timely, as spring training is starting this week.
I actually attended a ballgame once with a colleague from, I think, Germany. He picked up the game pretty quickly -- but danged if it wasn't one of the weirdest games I've ever seen. Finally, as the pitcher walked in a run with the bases loaded, with the crowd hooting and roaring even though nobody had hit the ball, he turned to me and said, "I give up." I bought him a beer anyway.
I agree with Isaac who is citing Einstein: "Keep it as simple as possible, no simpler".
Your guitar teacher was right: it should be an F#m b5 which contains the notes F#(r)-A(m3)-C(b5)-E(b7). It doesn't even contain a D(!) so your simplification of naming it a D7 is really incorrect. You have been misled by the fact that F# A and C occur in the D7 chord as F#(3) - A(5) - C(b7), but than you could mention Am also a C, or Em a G. All have there own place and musical function in a composition.
So, oversimplification may lead to misunderstanding and wrong conclusions. So here the best solution may be as with the IFR: it IS an F#m b5 chord and the 'why' (and why it's not a D7) will be explained by the time you really need it.
Wow, Anonymous, you know your stuff. But the three notes in question are F#, A, and C. These three notes also appear in the D7. True, the D is not even in this particular triad, but I often play a 7th chord on a keyboard by dropping the root note finger down to the flatted 7th, essentially playing a D7 on keyboard by playing C, F#, A. The three notes in the Dobro example are the 1st inversion of this very chord. Your point is well taken, it is an F#mb5, but how often have you ever come across that chord in a folk song in G? On the other hand, the D7 occurs naturally and frequently. So my interpretation of it as a 1st inversion D7 is a more viable explanation that will make me more likely to incorporate that particular fret pattern when playing, such as needing a transition run out of D and back to G, much more so than thinking of them as an F#mb5.
Over-simplified knowledge that informs correct action is better than accurate information that eludes application.
Post a Comment