A Book Is Not a Table of Contents
This post is part of my Medium blog.
I wrote four technical books for O'Reilly. The first was Jakarta Commons Cookbook in 2004. I remember the Word template, the chapter deadlines, and the stupid amount of time I spent making sure the thing was readable.
O'Reilly had a process. You wrote in Word. You followed the template. You sent the manuscript to the publisher and waited for an editor to find the mistakes you could no longer see after reading the same paragraph forty times.
The editing rounds were painful. That was part of why they were useful. Somebody else was reading the book as a reader instead of as the person who had spent the last year thinking about it. They could see what the book was actually doing because they weren't trapped inside its construction.
I'm dyslexic. I can write something that makes perfect sense in my head and leave out a small, necessary part of the sentence while doing it. A word disappears. A pronoun fails to arrive. It isn't optional when you're writing a book.
The editing process at O'Reilly was the first time somebody else's reading fixed what my reading couldn't. An editor would send back a chapter with a note: "You said this in chapter two and the opposite in chapter five. Which one do you mean?" I would stare at both passages and realize I had changed my mind between drafts without telling anyone, including myself.
O'Reilly cared about whether a technical book had a narrative structure. It changed how I thought about technical writing. The publisher wanted to know what the book was really trying to say.
Most technical books don't do that. They are references. You look something up, find the example, copy the code, and close the book. O'Reilly wanted more. They wanted the reader to finish a chapter and understand something, not just have followed the steps.
I used the O'Reilly process when I wrote Redundant, even though Redundant is not a technical book. It is a novel about FinOps, organizational power, and how technical decisions become decisions about people. The technical material matters because it is the setting. But I didn't want to write a cloud-cost manual with character names inserted between the examples.
The book had to work as a story. The FinOps had to be real, but the story had to carry someone who doesn't know what FinOps is.
I wrote drafts. I rewrote them. I gave the manuscript to readers who didn't know cloud architecture and asked them what they thought was happening. When they said "I don't understand why this number matters," I didn't explain the number. I rewrote the scene until the number mattered to the reader who didn't know what it meant.
That is the work. Not the writing. The part where you find out what the book is actually about by showing it to people who don't know what you meant.
The book is not the output. The book is the artifact left after the process of discovering what you were trying to say. The process is what makes the book worth reading. The output is just the record.
That is what the editing process taught me. Not that the editor is always right. The useful part is that another person forces you to explain what the thing you are making actually is.
AI can help with the writing. It can't do that part. The part where another person's confusion reveals that your clarity was only clarity to you.