A Book Is Not a Table of Contents
I approached O’Reilly with a ridiculous amount of respect.
I had grown up on those books. In high school, and later when Linux was still new enough that every installation felt like a small act of faith, I was reading books about Windows, Unix, C, and the various tools that made computers useful. There was a book about sed and awk. There were books about systems I didn’t fully understand yet. I learned how to program from books like that.
You bought the book, put it next to the computer, and kept it there until the cover started to separate from the pages. I remember typing in BASIC programs from a book of code for the TRS-80 when I was 8 years old, and then in the 1990s you always had that Peter Norton book on assembly around, even though you didn’t understand it. For me, O’Reilly books were the ingredient that took me from a heavy computer user to someone who was coding in the mid and late nineties.
Fast forward to the early aughts and books were how you learned.
By the time I published with O’Reilly, I understood what those books had done for me. I wasn’t just sending a manuscript to a publisher. I was joining a tradition that had taught me how to do the work in the first place.
I wrote Jakarta Commons Cookbook for O’Reilly in 2004. I co-wrote Maven: A Developer’s Notebook with Vincent Massol. I wrote Maven: The Definitive Guide. I contributed to Harnessing Hibernate with James Elliott and Ryan Fowler.
I wasn’t a good writer. I was a programmer who had been given a book contract. Those are different things.
The process helped.
A technical book takes a long time. You write the material. You test the examples. You discover that the thing you thought was obvious is not obvious at all. The biggest surprise after writing the first draft is that the editor reminds you that you cannot assume anything. Readers didn’t buy the book for the things you already understand. You need to explain everything, including the part you thought everybody knew.
Then you do it again.
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 the shape of the thing because they weren’t trapped inside its construction.
O’Reilly cared about whether a technical book had a narrative structure. That was my experience there, and it changed the way I thought about technical writing. It wasn’t enough to say, “Here is a book about XML,” or “Here is a table of contents that covers all the features.” The publisher wanted to know what the book was really trying to say.
A technical book can list a series of topics and provide detailed explanations, and many technical books do exactly that. But if the book has no structure and no arc, it isn’t worth reading. A book can be accurate and still be useless. A full table of contents does not mean the book has an argument. Structure is what keeps the reader moving through the material instead of leaving them with a pile of explanations.
It also explains why the old publishing process took so long. A book might take a year to write, and then it would pass through editorial review, technical review, copy editing, production, and the final round of corrections. Every round was another opportunity for somebody to say that the thing you had written was not yet the thing you meant. But there was another person reading what you wrote and trying to make sure that the reader was represented.
That part of publishing has changed. The old computer-book era is mostly gone. I rarely see anyone in an office with a technical book open beside their laptop now. The reference material moved into search results, documentation, forums, code completion, and whatever answer an agent produces while you’re trying to remember which command you need.
That change is useful. I’m not interested in pretending otherwise. I like being able to search a manual. I like not needing to own three hundred pages of Java reference material to find one method signature.
But we went from a world where a technical book could be close to a work of art, with that Peter Norton book as one example, to a world in which documentation is an afterthought. You can now have Generative AI generate something that appears to be a book in a few minutes without having to stop to think at all. (And many have done that.)
This is why I get irritated when people treat AI-generated books as a writing problem. The problem is that a lot of the content that’s being produced with Generative AI these days hasn’t been designed with a purpose. We went from books that had to survive editors, technical reviewers, and readers to poorly written books that can be generated before anyone has decided what the book is for.
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 the way technical decisions become decisions about people. The technical material matters because it is the setting and because the work has to feel real. But I didn’t want to write a cloud-cost manual with character names inserted between the examples.
I wanted to know what the book was really about before I wrote the book.
The book starts with Rob Coleman, a director of FinOps, being summoned to a meeting of the company’s vice presidents. He’s good at his job. He understands the architecture behind the bill, the organizational decisions behind the architecture, and the uncomfortable consequences that appear when somebody asks the numbers to support a story they already believe.
He is also in a job that nobody fully understands and that rarely gets people promoted. FinOps sits between finance and engineering. Everyone needs it. Neither side completely claims it. That is a useful starting point for a novel because it puts the main character in the room while keeping him outside the conversation that matters.
The book is not just about that meeting. The meeting is the door.
Something is happening inside the company, and Rob can tell that he is not being briefed into it. The story develops from that pressure. The FinOps material gives the book a real working environment, but the narrative has somewhere else to go. I’m not going to explain where. That would be an irritating way to sell a novel, and I have enough respect for the reader not to do it.
The same discipline applies to the rest of the trilogy. The books are about what happens when a person who understands cost and responsibility is pulled into larger questions about work, institutions, AI, and who gets to decide what the machines are allowed to do.
Those ideas are there because I wanted them there. They are not decorations added after the plot was finished.
A technical book teaches you how something works. A novel using technical material is trying to show you what the thing does to people. Both forms need structure.
A novel can have accurate details and still be boring. It can have a compelling premise and still collapse in the middle. It can have characters who say intelligent things and still feel like a meeting transcript written by somebody who has recently discovered dialogue. The work is deciding what belongs, when it belongs, and what the reader should understand before the next thing happens.
Generative AI is changing the economics of publishing and making it easier to produce books without doing the work that makes books worth reading. I’m trying to use the same technology in the opposite direction: to help me publish books that have a purpose, a structure, and something to say. Books that are more than the output.
HQ 8 — Authored. Drafted from dictated notes, revised by hand, AI used for grammar and polish only.
In Redundant, the first book in The Condition Set trilogy, Rob Coleman runs the FinOps review that names the waste nobody wants to hear about. The numbers don't change. The question is who they get used against.