I recently started reading the book “Docs for Developers: An Engineer’s Field Guide to Technical Writing” by Bhatti & Co. In this, the very first thing they touch upon is the concept of “The curse of knowledge”:
“The curse of knowledge, also called the curse of expertise or expert’s curse, is a cognitive bias that occurs when a person who has specialized knowledge assumes that others share in that knowledge.” - Wikipedia
I’ve previously heard of the bias, and am aware of its existence. However, after having read about its presence when writing technical documentation I often find myself wondering whether what I write reflects this bias.
Technical documentation comes in many flavors, and with many different intents. The technical documentation I usually write serves one of several purposes: to share knowledge about how a system works, to explain a process, or to guide consumers of a service my team provides.
This documentation doesn’t necessarily emerge on its own. It’s often something that is created when I’m designing the system, or have to help a colleague with debugging that exact problem. My manager gave a great hint on when to write documentation: when you’re deeply immersed in the task or problem. This is when you are the most knowledgeable about that exact situation, and also where your knowledge about the problem is fresh.
However, this is also where the curse of knowledge is most prevalent. When you’ve been sitting with a problem, figuring out all of its intricacies, that’s where you tend to forget that your peers don’t have the same insight as you.
When I reach that point, I’ve started asking myself whether the documentation I produce shows signs of the curse of knowledge. A good litmus test for this is to ask for a peer review from a colleague, and see whether they’re able to understand the documentation. If they aren’t, then it requires another iteration.
Writing technical documentation is hard. And writing good technical documentation is even harder. It’s a skill that’s honed over a long period, and takes continuous practice to keep sharp. For many, it’s often seen as tedious, but I view it as essential to the role of a Software Engineer.