The Curse of Knowlege

Have you ever been in a conversation that went something like this?

A: "Visual Basic? It’s really easy. You just code it."

Matt: "What do you mean?"

A: "There’s really nothing to explain, you just do it."

Or perhaps:

A: "Does everyone know what page objects are?"

Matt: (Raises hand) "I might, but my readers might not. Could you explain it for us?"

A: "You know, Page Objects!"

Matt: "Right, you said that. But what are they?"

A: "You use the page objects pattern!"

Matt: "Right. And what is that?"

A (frustrated): "You can look it up on wikipedia."

I’ve had similar conversations about "architecture", "coaching", "management" and, of course, "quality."

Visual Basic and Page Objects 

Here are two answers that would have helped me:

Visual Basic: "Start out with a blank window. It’s your application; you drag objects onto it - text boxes, buttons, that kind of thing. You can change the properties of the objects, drag to expand, double click to write the code, say when a button is clicked. The code is very similar to traditional basic."

Or perhaps:

Page Objects: "Encapsulate what the page can do in methods and the data in members of class, and use the class to write test tooling. That way, when the user interface changes, you have separated things so you only need to make changes in one place - then suddenly everything else works."

How hard was that? Gosh, the people in the example above must be totally incompetent at explanation?

Not always. They may be suffering from the curse of knowledge.

What’s the Curse of Knowledge?

Imagine having a conversation about algebra when someone raises a hand and asks "what is subtraction?"

It’d be pretty frustrating, wouldn’t it?

You might be tempted to tell the person to go read a second grade math book and come back when they understood it, but at least you’d recognize there is a problem.

In software, we often can not fathom the possibility that the other person doesn’t understand. That is what Dan and Chip Heath label "the curse of knowledge" in their book Made to Stick.

It happens all too often.

Think about a young, newly promoted programmer trying to explain a technical approach to a older, non-technical executive. The programmer genuinely can’t understand why the executive just doesn’t get it, while the executive is thinking “we need to hire someone to manage these programmers who speaks English.”

We "get" that the bug report entered by customer service is too vague (“save does not work”), but we often “miss” that our bug reports require special knowledge. For example, here’s a complete, correct bug reproduction to a company I worked with:

To reproduce, untar the standard test database and log in as user [email protected], then go to the “searchExample” page. Now add the tag for matt and immediately search for matt; the page does not appear!

You’ll notice I didn’t say where to get the standard test database from, how to untar, how to load it in, or the password for the devnull user. (Of the few thousand people who read this next month, some are bound to ask what a tar ball is, while others will actually know the company I am describing above, and would think I could describe the bug above in four or five words.)

At the opposite end of the spectrum, we can assume our audience knows nothing and talk to them like fourth graders — our bug reports could all start with "double click on internet explorer. Wait for internet explorer to appear. Click on the address bar. Type in www.testurl.com. Wait for login page to appear."

ugh.

I'm bored typing that.

That challenge is to customize our message for the audience; to write or speak to the right level. That means what we say to an analyst might be different than what we say to a programmer, and we probably do this instinctively. Yet do we think about it?

Based on the number of times I hear "you know, you just do it", I suspect we don’t think about audience, and instead suffer from the curse of knowledge, far too often.

A Place To Start

Get conscious about your audience, and whether they prefer power (smaller, compact sentences) or detail. If you can't get a feel for it, consider writing the material from multiple angles and asking your audience which they like more. If you’ve had friction in the past over writing that needs to be “better” without details, this can break the logjam.

What's Next

My goal with this post was to point out the gap between audience and expert. Sometimes, just knowing the gap can help produce a better bug reproduction. That’s great. 

The next problem is how to write it up without putting our reader to sleep - to balance detail with abstraction. Even if we get their attention, we need to keep the attention of a diversity of reader - includng PM, the developer, the non-technical business customer, the support rep … and they will all be motivated by different things. Some understand what we mean by 'tarball', others do not.

Maybe we can talk about that next time.