I have a friend, a fellow writer, who is also a mentor and colleague. One day, he wrote an essay at Google titled: “The docs are broken!” (Followed by the subheading: “O rly?”)
It’s one of my favorite essays. In it, my friend writes about how people who are “content adjacent” (my phrase, not his), often come running to the technical writer, saying that the docs are terrible and need to be fixed. What usually happens (and what prompts his rather snarky subheading) is that someone couldn’t find a piece of information, made a complaint, and now Everything Is Terrible And We Have To Rewrite Everything.
(In the words of the late Douglas Adams, “Capital letters were always the best way of dealing with things you didn’t have a good answer to.”)
What my friend pointed out was that, often, the docs were not necessarily broken. There was a data point where someone got confused. A cause for an investigation, for sure, but not one for alarm.
My friend’s essay always stuck with me. And it prompted me to go a little further. Part of the problem, I think, that these content-adjacent roles have, is that they lack the vocabulary to describe what they want to improve in the docs. To them, documentation quality is binary: it’s either there or it isn’t. But the reality is more nuanced. There are different aspects, or what I call characteristics of content quality.
Every writer I know has their own definition of what these characteristics are. In the following chapters, you’ll learn about mine. As you read, remember: it’s okay if you disagree with these characteristics. In a way, that’s not the point. The point is that you define some set of characteristics, building a vocabulary and a framework that helps everyone better understand what’s meant when we talk about content and quality.
Most experienced technical writers already think about accuracy and completeness, even if they don’t use those exact words. What I found valuable was having a shared vocabulary — a way to move conversations about content quality beyond “this feels right” or “these docs need work.” The chapters that follow explore each characteristic in turn, starting with the framework as a whole and then examining what each dimension looks like in practice.