Chapter 4: The Six Characteristics of Quality

When I first started to think about content quality, I wasn’t interested in creating something for anyone to use. What I really wanted was just clarity in my own mind. If I had a clear idea of what quality meant for me, I could use that as a north star in my work. And, I could use that definition to articulate why I was making specific content decisions to my team.

But I didn’t know how to put this definition together myself. I didn’t have the tools to describe the problem, let alone to explain the solution.

I probably would still be stuck in this state if I hadn’t had the opportunity to work with a user experience researcher on one of my Google projects. I pointed out that one of the problems I had with measuring quality is that it felt hard to pin down. This researcher suggested I think about the problem in terms of heuristics instead of a set of rules. Basically, he was helping me find ideas that were “good enough,” rather than finding ideas that were perfect.

I must admit, when he first brought the idea up, I was resistant. The whole point of defining quality was, in my mind, an opportunity to provide the same level of clarity and crispness that we applied to code analysis. I wanted to build something that allowed my writing, my work, to stand on equal footing with the code.

What brought me around to his way of thinking was something totally unrelated—my internet. One weekend, I was installing some new wireless access points in my house. I had been spending hours moving an access point from one place to another, trying to get the best connectivity possible. I was getting pretty frustrated with my progress, when my neighbor pointed out:

“Hey, eventually it’s just numbers. What matters is the result. If the connection is solid, that’s all that’s important.”

That’s what the user researcher was talking about. I didn’t need to come up with hard and fast numbers about quality. What I needed was a set of ideas, of characteristics, that got me the result that mattered. In this case, content that served the needs of the reader and of the product team. Content that was maintainable. Content that was useful.

When I let go of being perfect, I found that a set of six characteristics fell into place. Characteristics that, when combined, could help me move closer to creating quality content.

The Six Characteristics

Here are the six characteristics that I think help define content quality.

• Accuracy: Is what you’re telling users correct?

• Completeness: Are you providing the information that users need to succeed in their specific workflows?

• Conciseness: Does your content respect your readers’ time?

• Discoverability: Can users find the information they need, when they need it?

• Consistency: Are you using the same words, phrases, and structures across your documentation?

• Meaning: Is the information you’re providing relevant and actionable for the reader?

I’ve listed these characteristics with what is basically a “yes/no” question to help define them. But it’s important to understand that each one of these characteristics has nuance. Accuracy, for example, is more than just being factually correct. It requires understanding the user where they are in their journey. Someone new to a topic might need greater detail than someone with more experienced. And sometimes, the opposite is true. (I discuss this in more detail in Chapter 5.)

Completeness, on the other hand, means one thing when you’re talking about a tutorial, and quite another when you’re talking about an API reference. (I talk about that more in Chapter 6.)

My point is: each of these characteristics has to act as sort of a framework-within-a-framework. If you treat them as simple “true/false” statements, you won’t get a real understanding of the quality of your work.

Signal versus score

I learned something else from the UX Researcher. One of the ideas he drilled into me over and over again was this: these characteristics provide signals. They aren’t scores.

At first, I wasn’t sure I understood the difference between the two. If content wasn’t accurate, it wasn’t accurate—I should go fix it. And I admit that I’m not a data scientist, so I probably still don’t have a complete understanding between the two terms.

What I did come to understand is this: these characteristics, whether alone or in combination, do not provide a definitive answer regarding the quality of your content. Instead, what they do is provide signposts, lighted pathways, that encourage you to explore that characteristic in more detail. If your content seems to fall short when it comes to accuracy, that doesn’t necessarily mean the content is inaccurate. It means that accuracy is something you should research further. Perhaps the content is accurate, but for the wrong type of user. Perhaps the code examples are correct, but the explanations of that code are wrong.

In other words, these characteristics allow you to start your journey. And, in my opinion, that’s enough.

A quick note on how these characteristics intersect

One of my passions in life is Aikido. And in my style, we had a set of principles that we displayed in the front of the dojo:

• Keep one point (your center of balance)
• Relax
• Positive mind
• Correct posture

This isn’t a book about aikido, so I won’t go into these principles in detail. But I bring them up because, when we talked about them in class, we often pointed out that all four of these principles intersect. If you have your center of balance, you were relaxed. You had a positive mindset. And you likely had good posture. On the other hand, if your posture was bad, you probably were holding tension, which meant you weren’t relaxed. You probably didn’t have a positive mindset, and you probably didn’t have your balance.

In other words, if you had one principle, you probably had all four. And if you didn’t have one, you probably lacked all of them.

The same is true of this quality characteristics. Each one intersects. What affects accuracy also affects completeness. What impacts conciseness also impacts meaning. And so on. You’ll see, as you read through these chapters, that some of my examples could easily be moved to a different characteristic. I’m okay with that; after all, the point here is to build a vocabulary, not create another set of rules.