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.

Principles

  • 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.” github.com. 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.

Lab Notebooks

* Always in pen

Your goal is not to preserve the outcome of your thoughts — that’s your code. Your goal is to preserve the process of your thoughts. So no erasing, no blacking out. You can put a single line through anything spelled or written incorrectly.

* Always during

Write down what the problem is, what you’re about to do, and what you expect the result to be. Treat your work as an experiment! This is especially valuable for junior developers who are still in a “try everything until something works” frame of mind. Forcing yourself to hypothesize what’s actually wrong is really valuable; and there’s nothing wrong with expecting a negative result (“I don’t think the problem is X, but it’s easy to prove it, so…”) If during the actual process, you deviate from your written plan, write down the deviation, and why you’re doing so. Don’t wait until after you’re “done” — because “done” might mean six hours from now.

* Always forward.

If you write something on Monday and realize you were wrong on Tuesday, write the correction in Tuesday’s entry. This is a lab journal — from the French “daily”. If you had a misconception, you want a record of that, as well as a record of why you were wrong. You can (and should) add a small note to the original entry pointing to the page where you correct yourself — but don’t obscure what you originally wrote.

* Keep a table of contents

The first pages of your notebook should be a table of contents; with a few words summarizing what is on each page. Make it easy to answer questions about what you did, and why, even if years have passed.

* Keep a habit

At the start of each day, read yesterday’s pages. Write down what you intend to do today. At the end of each day, read through today’s pages, and add an entry to your table of contents.

* Summarize when necessary

If you’ve spent a messy week going round in circles, and you lab notebook has become hard to follow, feel free to take a page to summarize what you’ve learned and where you ended up. Flag it specially in your table of contents.

* Store safely

At the end of a project, label the spine of your notebook, and store it safely with your others. It should be easy to access if questions ever come up.”

—Sam Bleckley, “Lab Notebooks.” SamBleckley.com.

A Theory of Documentation

“Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances – so software usually needs them all.

And documentation needs to be explicitly structured around them, and they all must be kept separate and distinct from each other.”

—Daniele Procida, “What nobody tells you about documentation.” Divio. Accessed: November 12, 2018.

Probably applicable to any kind of documentation process you need to replicate, not just for software.