Chapter 1: The dinner party

In a sleepy gated community on the outskirts of Augusta, Georgia, the event of the season is about to take place.

It's a semi-occasional party that my parents throw. They call these parties, soirees, and they usually occur when a particular mood strikes them to do so. Both of my parents are talented musicians. My father, a renowned psychiatrist, has played piano for decades while my stepmother, is a vocalist and skilled pianist in her own right. These soirees are often opportunities for my parents to share their considerable skills with select friends and family. The backyard is converted into an outdoor amphitheater. Special guests are invited to perform. The evening usually involves some very talented performances, accompanied by a reasonably polite amount of liquor.

They're a good time.

I've only attended one of these soirees. The fact that they occur in Augusta while I and my family live in Seattle means that a weekend jaunt is close to out of the question. However, every now and again the stars align and fortune smiles. I had found a good deal on airfare for just that particular weekend, so I was able to attend. Even better: my brother, a talented jazz saxophonist, was going to perform at the soiree as well. And so the weekend was shaping up to be a fun, informal, family gathering.

The night of the soiree arrives and the house is buzzing with activity. The backyard is set up with at least a hundred chairs. No easy feat considering that most of the yard is taken up by a swimming pool. (More than once I wondered if one of the attendees would fall in at some point during the evening. No one did.) Sound checks were done, programs were printed. And, as the one member of the family who does not play an instrument, I found myself with the all important job of vehicle logistics. Okay, okay--I stood out front and told people where to park.

It didn't take long until all the guests had arrived and the first round of libations consumed. I sat and enjoyed listening to the first set of performances--but still kept an eye on folks as they walked perilously close to the edge of the pool.

During an intermission, I wandered from the backyard and into the house, where a number of guests were getting drinks and having conversations. I smiled and nodded as I walked by–my mind admittedly on some lemon tarts I had seen on a tray somewhere in the kitchen. As I passed, I did what I usually did–I tried to guess how these people knew my parents. Some were no doubt parents of children to whom my stepmom taught piano. Others were likely doctors and professors that knew my dad professionally. Still others were acquaintances from their country club. I was usually wrong in most of my guesses, but it was fun to try.

As I maneuvered myself closer and closer to the kitchen, I soon spotted the lemon tarts I was looking for. But before I could reach them, a woman's voice stopped me.

"Excuse me," the voice said. "But are you related to Dr. Shevitz?"

I realize that you're likely reading these words, so you can be forgiven for not understanding the somewhat ridiculousness of the question. You see, I look nearly identical to a younger version of my dad. We have the same nose, the same smile, the same relative build. If you were to see a picture of my dad and I, side by side, you might wonder if someone had built a time machine. So when someone asks me if I'm related to my dad, it's a little like asking the sun if it belongs in the sky.

Nonetheless, I suppose it would be rude to just assume that I was related in some way. There's a chance, after all, that there is some quirk of universal genetics at work. So I smiled and turned to put a face to the voice. It belonged to a woman just a little older than myself. She was standing with a small group of men and women, who also turned to look at me.

"Why yes," I responded. "I'm Dave. I'm Dr. Shevitz's son."

"Oh!" The woman exclaimed. "You must be his OTHER son. Your brother is the one who plays the saxophone."

This was not the first time I'd participated in a conversation like this. So I kept my smile in place. "That's right," I replied. There wasn't a need to add any more than that.

One of the men spoke up. "You have a talented family!" he said. "Your father is great at the piano. And Lynda"--my stepmom–"has such a powerful voice! And your brother is just amazing as well."

I'm happy to accept compliments about the talents of my family–I really am. So I was genuine when I said: "I couldn't agree more."

"Tell me," the man continued, "do you play an instrument?"

I've gotten this question quite often over the years as well. I had my answer ready. "Not well enough for an event like this, I'm afraid." Unless a soiree was going to focus on the rhythm chords of AC/DC's "You shook me (all night long)" I wasn't going to be performing for this crowd any time soon.

The faces of this little group shifted into one of those expressions that is intended to convey sympathetic pity. "Oh," one of them said. There was a lengthy pause.

"So, what do YOU do?"

I have always found this question an interesting one to answer, especially because I've spent decades working for technology companies. Companies like Microsoft, Amazon, and Google have powerful roles in all of our lives—yet most people don't really know how these companies work. The easy answers—"I work for Amazon" or "I work in high tech"—usually imply that you're a software engineer.

There's nothing wrong with being a software engineer, but there are so many "tech adjacent" jobs that are essential for these companies to operate. Product Managers, Developer Advocates, Technical Writers—these roles do a lot to ensure that a given product release delights our intended customers. I'm always drawn toward advocating for these different roles, toward raising awareness of them in the minds of the public. Not only because I'm proud of what we do, but because it opens the door for other people who see the world of these technology companies and want to find a way to be a part of it. Not everyone wants to be an engineer, and that's okay.

Of course, the folks in my family's kitchen are not interested in a lecture. They're asking a polite question. I've tried several "elevator pitches" to convey what I do accurately, but they so far have all fallen short. "I write documentation," is too vague. "I explain how code works to developers," was better, but still not enough.

Standing there in that kitchen, surrounded by the sounds of my brother's saxophone drifting in from the backyard, I realized I was about to attempt yet another explanation that would probably fall flat. But I had to try.

"I'm a technical writer," I said.

The blank stares began almost immediately.

"Like instruction manuals?" someone asked.

"Not exactly," I replied, already feeling the familiar frustration building. "I write for software developers. I help them understand how to use the tools and services that other developers build."

More blank stares. I could see them trying to process this—developers helping other developers? Isn't that redundant?

I could tell I was running out of time. So I went to my default: "You know how, when you buy a new TV or microwave, it comes with a manual? A manual you never read?" That got a few smiles. "Well, it turns out developers also don't like to read. And I write manuals for them."

Everyone chuckled and the conversation moved on, their temporary curiosity satisfied.

Over the past few years, I've found that this humorous answer gnaws at me. Why don't developers like to read? It's almost a common joke among my technical writer friends: "We write things no one wants to read." In fact, when I mentor new writers, I often tell them:

"Remember, always assume that your audience is angry. They're angry because they couldn't figure out how to write the code they need to write, and now they have to read the documentation."

I still think this is good advice, but how did we get to this point?

As I've thought about this question over the years, I keep coming back to one idea: quality. We've spent so long not caring about content quality, treating technical docs like a box we need to check before shipping a new release. We don't focus on writing well, on maintaining existing documentation, on building thoughtful experiences. These shortcomings don't come from any malicious intent—even the largest companies care a lot about customer experiences. Instead, documentation is often a trade-off as teams put more focus on the things they can measure: deployment frequencies, shipped features, and so on.

This deprioritization of quality documentation is one reason that I both love and fear the introduction of AI tools. I love these tools because, when used correctly, they can help everyone create content faster. And I fear these tools because they are only as good as the data they're trained on. And we've had decades of bad documentation.

We need to think more about the quality of our technical writing. Like Phaedrus in Zen and the Art of Motorcycle Maintenance, we need to care about doing the work well, not just getting it done. Pirsig wrote about quality as something that can't be defined but is immediately recognizable—you know good work when you see it, whether it's a perfectly tuned engine or a piece of writing that actually helps someone solve their problem.

In technical writing, quality isn't just about correct grammar or following style guides. It's about understanding your audience so deeply that you can anticipate their questions. It's about organizing information in a way that matches how people actually work. It's about caring enough to test your instructions, to revise when something doesn't work, to maintain content as systems evolve.

Quality technical writing doesn't just inform—it empowers. It transforms frustration into confidence, confusion into clarity. When we commit to quality in our technical writing, we stop writing things people don't want to read and start writing things they're grateful to find.

While we may not be able to define quality in technical writing with a single sentence, we can identify its characteristics. We can recognize the patterns that separate documentation that helps from documentation that frustrates. We can name the qualities that make some technical writing indispensable and other technical writing ignored.

That's what this book is about: identifying quality's characteristics and learning how to achieve them.