…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 questions, especially 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.