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.
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. Weaving between guests, 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 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.” There was a pause, then: “So, what do YOU do?”
“I’m a technical writer,” I said. “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.
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.
That’s what this book is about: identifying quality’s characteristics and learning how to achieve them.