The Curse of Knowledge is a cognitive bias where you have knowledge that another person does not and you have forgotten what it was like to NOT have that knowledge. This makes it harder to explain things to a person who knows less than you do about a given subject.

The Curse of Knowledge has a huge impact on the process of technical documentation, as well as on how useful and helpful technical documentation is.

We have all had the experience of reading instructions where we felt completely lost, only to find out later that the writers of the instructions had assumed we knew something that we did not. We have all had the experience of answering a friend or family member’s question and thinking “duh. How can they not know that?” This last experience seems to happen to teens in a larger percentage than to others, just ask my 14-year old. I can’t count how many times his eyes have rolled when he’s asked to explain things in a different way or provide key information he had not offered previously.

As we learn anything, we subconsciously streamline and integrate the knowledge we gain into our behaviors and memory. It will get to the point that we no longer consciously think about why we do something a certain way or know exactly how to approach a task. We just do it.

We are making assumptions, both consciously and subconsciously, about what the other person knows. This is a problem in all technical writing but especially so when it comes to software and technology.

We tend to assume that other people have the same body of knowledge and skills that we have and are surprised when they don’t. As an example, if we use a particular operating system for a while, we tend to know its oddities and if we switch to another operating system, we must try to figure out how to perform common tasks all over again. I know my first frustration on a Mac was trying to figure out how to eject a CD. I finally had to ask someone.  I am not a computer newbie, but dragging the disk image to the trash never occurred to me. Yet it was completely obvious to my Mac-using friends. If I had been trying to follow documentation written by someone familiar with a Mac that just said “eject the cd,” I would have been very frustrated and annoyed. Yet they may have thought that this task was so simple and obvious, it didn’t bear mentioning in any more detail.

Technical writing involves a constant balancing act between the Curse of Knowledge and the assumptions made under it, and not wanting to document every intricacy that isn’t the core focus of your documentation.

An example of the Curse of Knowledge

Consider a simple example: Making a phone call on an old-fashioned, hard-wired, rotary phone. Most of us would know to pick up the handset and then dial the number we want to reach. We know that if we are dialing another area code, we need to dial a 1 and then the full phone number, including the area code, that we want to reach. If we are dialing a local area code, we dial just the seven-digit phone number. If we need to call emergency services, we just enter the three digit code for the one we need.

So very simple, right? So basic. Most of us grew up with this sort of a device or a similar one, an interface to the telephone network, and take it completely for granted that we know how to operate it.

Now force yourself to consider this as if you had never seen a telephone before. Would you even know what the device does? Would you know what the handset is or does? Or how to hold it? Would you know about phone numbers, how they work, and how to call one? How about an event sequence like:

  1. Lift handset.
  2. Place the speaker end of the handset to your ear and listen for a steady tone.
  3. If a steady tone is present, dial the phone number you wish to reach. For  each digit of the telephone number, in sequence:
    1. Place a finger into the hole of the dial labeled with the digit you want to dial.
    2. Using your finger, rotate the dial to the right until your finger meets the metal stop.
    3. Remove your finger from the hole and release the dial so it rotates back to its starting orientation.
    4. Repeat this sequence until each digit of the telephone number is dialed.
  4. After the entire telephone number is dialed, keep the handset to your ear to listen for a response.

I haven’t even talked about things like what happens if you take too long between digits, what happens if you get a human operator, what the possible responses are (ring tone, busy tone, error message, etc.) Nor have I shown a diagram or otherwise explained what the parts of the phone are or what part of the handset is the speaker part.

Assumptions are universal in human behavior, but they need to be recognized and questioned.  This is especially true in technical writing. Every time you think “Oh, the users will know that,” you need to ask yourself why you believe that to be true, whether it’s a valid assumption, and if you are willing to accept the consequences if it is incorrect.

How much do you document?

There are limits to how much you need to or can include in your documentation, given the constraints of time, space, and documentation focus. There are certainly levels of information and knowledge you would expect an average user to have, depending on what you are writing documentation for.

The real question with more technical documentation is where to draw that line to enable new or beginning users to use your product along with much more advanced users. A common failing in technical documentation is to write to the average or advanced user, resist doing any user education that is more general or conceptual, and only document your own product in isolation. This usually creates a knowledge gap that is difficult to bridge because someone picking up your product to use it often doesn’t know what gaps there in their knowledge until they fall into them.

Unfortunately, this often drives people away from using your product. How many times have we all heard complaints about documentation and how much it sucks and how much it leaves out? I firmly believe that a lot of documentation is so tightly scoped that it does its users a disservice in the end. Sure, you don’t want to be trying to include an encyclopedia of knowledge in everything you write, but some additional details when it would help the users is always a good idea.

Challenge your assumptions

There is certainly a base level of knowledge even a newbie would most likely have. For example, in the case of software, it’s perfectly reasonable to say “enter a string” in a UI and expect a user of developer-focused software to know:

  • How to navigate to the field where they can enter the information.
  • How to use their keyboard to enter information.
  • What a string is (though you might want to tell them any restrictions like length, character set, etc.).

You wouldn’t have to explain how to turn on the computer, how to sign in, etc. I would judge those as far too basic for someone trying to use a developer-focused piece of software.

But how can you tell which assumptions are reasonable and acceptable and which assumptions need to be discarded?

It’s often helpful to list out the assumptions you are making for the users of your documentation ahead of time so you can assess how much detail to include in the documentation and keep it consistent. The use of personas can sometimes help here, but I find they often actually muddy the water because the box created by a persona description isn’t as diverse as the real-world tends to be and still relies on assumptions of what that a person in that role will know. For example, it’s not a given that a developer is an expert user of the particular language you need and it’s not a given that a network engineer will know everything there is to know about every network protocol.

Instead, I prefer to  make a list things like:

  • What tools or software does the user need to have?
  • What level of experience does the user need to have with each tool or software?
  • What outside or environmental knowledge does the user need to have?
  • What language or languages does the user need to speak to use the product and to use the documentation?
  • What internet access, does the user need to have for the product and for the documentation.
  • What physical abilities does the user need to have?

Each of these bullet points gives me a chance to examine my assumptions as I write my product’s documentation. Each time I am writing instructions that touches on one of these listed areas, I think about any assumptions I am making and whether my users would be better served if I provide any key information I am assuming they know for easy reference. Some of them even cause me to question if the way my documentation is being delivered is adequate or needs expansion or change.

I also consider it a good practice to include reference links or a bit of additional information when I am documenting something confusing. I may not want to repeat some base information, but I am often able to provide a few links on where to go for more information. This does fly a bit in the face of some of the moves to much more streamlined documentation and the attitudes vary among types of documentation and company policies, but I’ve fought the battle more than once to get a paragraph or two of more basic information into documentation when I feel it will really benefit users and might reduce frustration or questions to customer support. This is especially true if the more basic information helps explain how my product interacts with or relates to things outside the product or key concepts.

When you publish your documentation, you should make an effort to list key prerequisites for those using your documentation. This can help your users tell if the documentation is at a level they feel comfortable with.

The Curse of Knowing is an important thing to remember and recognize when you are writing technical documentation and setting your bar for prerequisites and assumptions correctly can mean the difference between “okay” documentation and “excellent” documentation.

Photo credit: alex.ragone / / CC BY-NC-SA