Documentation As Empathy

…Writing documentation is an exercise in empathy. We’re not describing an objective reality – the source code already does that. Our job is to help shape the relationship between users and the Vue ecosystem. This ever-evolving guide provides some rules and recommendations on how to do that consistently within the Vue ecosystem.


  • A feature doesn’t exist until it’s well documented.
  • Respect users’ cognitive capacity (i.e. brain power). When a user starts reading, they begin with a certain amount of limited brain power and when they run out, they stop learning.
    • Cognitive capacity is depleted faster by complex sentences, having to learn more than one concept at a time, and abstract examples that don’t directly relate to a user’s work.
    • Cognitive capacity is depleted more slowly when we help them feel consistently smart, powerful, and curious. Breaking things down into digestible pieces and minding the flow of the document can help keep them in this state.
  • Always try to see from the user’s perspective. When we understand something thoroughly, it becomes obvious to us. This is called the curse of knowledge. In order to write good documentation, try to remember what you first needed to know when learning this concept. What jargon did you need to learn? What did you misunderstand? What took a long time to really grasp? Good documentation meets users where they are. It can be helpful to practice explaining the concept to people in person before.
  • Describe the problem first, then the solution. Before showing how a feature works, it’s important to explain why it exists. Otherwise, users won’t have the context to know if this information is important to them (is it a problem they experience?) or what prior knowledge/experience to connect it to.
  • While writing, don’t be afraid to ask questionsespecially if you’re afraid they might be “dumb”. Being vulnerable is hard, but it’s the only way for us to more fully understand what we need to explain.
  • Be involved in feature discussions. The best APIs come from documentation-driven development, where we build features that are easy to explain, rather than trying to figure out how to explain them later. Asking questions (especially “dumb” questions) earlier often helps reveal confusions, inconsistencies, and problematic behavior before a breaking change would be required to fix them.
-Evan You, et al. “Vue Docs Writing Guide.” Accessed: November 16, 2022.

I have been thinking a lot about this writing guide over the last few days. It takes a lot of caring to produce good documentation, particularly as you learn something so that you can overcome the curse of knowledge. I think much of this can be applied to writing more generally.

Mimesis, Unconscious Imitation

“What happened that night is something I now recognize as disruptive empathy. The cycle of conflict that stems from unchecked mimesis (unconscious imitation)—like that of a debt collector and a debtor, each responding mimetically to the aggression of the other—was derailed. There was an unexpected breaking in of empathy, something that transcended the moment. 

Fear, anxiety, and anger are easily amplified by mimesis. A colleague sends me an email that seems curt or disrespectful, I respond in kind; and passive aggression spreads like wildfire, beyond two people and through an entire organizational culture. 

René Girard uses the example of a handshake gone wrong to illustrate how deep-rooted mimesis is—and how it explains things we usually ascribe to simply being “reactionary.” There’s nothing trivial about a handshake. Say that you extend your hand to me, and I leave you hanging. I don’t imitate your ritual gesture. What happens? You become inhibited and withdraw—probably equally as much, and probably more, than you sensed I did to you. “We suppose that there is nothing more normal, more natural than this reaction, and yet a moment’s reflection will reveal its paradoxical character,” writes Girard. “If I decline to shake your hand, if, in short, I refuse to imitate you, then you are now the one who imitates me, by reproducing my refusal, by copying me instead. Imitation, which usually expresses agreement in this case, now serves to confirm and strengthen disagreement. Once again, in other words, imitation triumphs. Here we see how rigorously, how implacably mutual imitation structures even the simplest human relations.” 

This is how negative mimetic cycles start. We are not condemned to them, though. 

When we make the effort of getting to know people at their core, we reduce the possibility of cheap mimetic interactions. Knowing someone at their core requires sharing and listening to a particular kind of experience: stories of deeply fulfilling action. Knowing and relating to these stories produces empathy and a greater understanding of human behavior. 

A negative mimetic cycle is disrupted when two people, through empathy, stop seeing each other as rivals.”

-Luke Burgis, “Empathy Lessons … from a Hitman.” Arc Digital. June 15, 2021

Gardener’s Vision

“Without communication, connection, and empathy, it becomes easy for actors to take on the “gardener’s vision”: to treat those they are acting upon as less human or not human at all and to see the process of interacting with them as one of grooming, of control, of organization. This organization, far from being a laudable form of efficiency, is inseparable from dehumanization.”

—Os Keyes, “The Gardener’s Vision of Data.” Real Life. May 6, 2019.

Empathy Quotient

“The Empathy Quotient (EQ) is a 60-item questionnaire [snip] designed to measure empathy in adults…Clinically, the empathy measurements provided by the EQ are used by mental health professionals in assessing the level of social impairment in certain disorders like Autism. However, since levels of empathy vary significantly between individuals, even between those without any mental health disorders, it is also suitable for use as a casual measure of temperamental empathy by and for the general population.

[The link b]elow is a list of statements. Please read each statement carefully and rate how strongly you agree or disagree with it by selecting the circle under your answer. There are no right or wrong answers, or trick questions.

The Waiting Game | ProPublica

“Based on the real case files of five asylum seekers from five countries and interviews with the medical and legal professionals who evaluate and represent them, The Waiting Game is an experimental news game that lets you walk in the shoes of an asylum seeker, from the moment they choose to come to the United States to the final decision in the cases before an immigration judge.”

The Waiting Game