Prologue

When I was in college, one of my poetry professors gave our class an assignment.
"Write," he said, "a bad poem."

You'd think this was a simple enough assignment, but we were college students, and English majors at that. Our egos were strong. Each attempt at writing a bad poem failed. We'd dash off deliberately clumsy lines, force awkward rhymes, pile on clichés. But then we'd read them back in class, and someone would find something in them–an accidentally evocative image, an unintended rhythm that worked, a throwaway line that landed with unexpected weight. Even our most careless words seemed to contain, on later readings, some glimmer of insight or meaning. Not because they were brilliantly written, but because they had the potential to mean something–if not to the writer, then to someone, somewhere, in some context we hadn't imagined.

And that, of course, was our professor's point. As aspiring poets, we constantly gnashed our teeth and wiped our brows, worried that what we had written wasn't good enough. And yet, as our professor's assignment demonstrated, the very fact that we were trying to write well–that we cared–meant we were heading in the right direction. We might never write something that we ourselves thought was "good enough," but maybe that's okay. It is the pursuit of that goal that matters.

This idea–that quality emerges from care–is one of the core themes of Robert Pirsig's 1974 book, Zen and the Art of Motorcycle Maintenance.

What few people realize is that Pirsig wasn't just a philosopher contemplating quality in the abstract. While he was writing Zen and the Art of Motorcycle Maintenance, he was working as a technical writer at Honeywell, writing computer manuals. He would wake up early in the morning in his apartment above a shoe store in south Minneapolis and work on his philosophical exploration of Quality, then go to his day job and write documentation. For four years, he lived in both worlds simultaneously.

I've spent over 25 years as a technical writer in various forms, and I've thought a lot about Pirsig's dual life. Because here's the thing: poetry and philosophy can rest on care alone. You can write a poem, put your whole heart into it, and whether or not anyone calls it "good," you've created something meaningful. The care itself is enough.

Technical documentation doesn't have that luxury.

As technical writers, it is our job to care. We care about our customers, who depend on our words to build useful things. We care about the engineers we work with, who toil endlessly to build systems that are scalable, performant, and useful. But caring isn't sufficient. In engineering, anything that can't be measured becomes suspect as something unnecessary. You can't simply look at documentation and say, "These are good docs." You need data. You need metrics. You need a framework.

And yet, in my many years of technical writing, I've never found a satisfactory way of defining what quality means for documentation. We know it when we see it. We recognize bad docs immediately and good docs eventually. But we struggle to articulate what makes the difference.

I'm convinced that quality absolutely applies to technical writing–we've just lacked a working framework to define it. I wrote this book not as an attempt to create an authoritative standard for quality in technical writing. Instead, I hope to start a conversation among technical writers, engineers, users–anyone who engages with technical documentation. My hope is that the ideas here either support your own thinking or give you something to push against.

Because the pursuit of quality in technical writing matters. And it starts, as Pirsig understood, by caring enough to try.