Why Most Technical Books Fail

I have written several technical books. I have read far more. Most of them, including some I am not proud of, are bad. Not maliciously bad — the authors worked hard and meant well — but bad in ways that are entirely predictable and almost entirely avoidable.

After enough years on both sides of the page, the failures start to rhyme. Here is what I keep seeing.

They Teach the API, Not the Thinking Link to heading

The most common failure mode in technical books is mistaking coverage for education. The author lists every function, every flag, every option. The reader finishes the book knowing the surface of a library and nothing about how to think with it.

K&R did not teach you every C function. They taught you how C thinks about memory, about types, about the relationship between arrays and pointers. Once you understood that, you could look up the rest. The thinking was the content.

Most modern technical books invert this. They are organized like documentation, written like documentation and about as useful for learning as documentation. If a book can be replaced by reading the official docs more carefully, the book should not exist.

They Are Afraid to Have an Opinion Link to heading

Technical books hedge constantly. “Some developers prefer X, while others prefer Y.” “This approach has tradeoffs.” “It depends on your use case.” All of this is technically true and almost entirely useless.

You are reading a book because you want someone who knows more than you to tell you what they think. A book that refuses to do that has failed at its primary job. The best technical authors — Pike, Kernighan, Stevens — said what they thought, directly, and trusted the reader to push back. “Do not comment bad code — rewrite it.” That is a sentence with a spine. You can disagree with it, but you cannot mistake it for the author hiding. That directness is what made those books worth reading.

Hedging is not intellectual honesty. It is a way of avoiding the risk of being wrong, at the expense of being useful.

They Pad Link to heading

A technical book that should be 200 pages is published as 500 pages because publishers, and sometimes authors, believe that thickness signals value. It does not. It signals that nobody made the hard decisions about what to cut.

Every page that does not teach something costs the reader time and attention, and it costs them trust. When you realize that a chapter could have been half as long, you start skimming. When you start skimming, you miss things. The padding punishes careful readers and rewards skimmers, which is the opposite of what a good book should do.

The discipline required to write a short book is much greater than the discipline required to write a long one. Writing everything you know is easy. Writing only what matters is hard.

The Code Examples Are Toys Link to heading

This one is pervasive. The code in the book works, compiles, runs, and demonstrates the concept. It also bears no resemblance to real code because all the error handling has been removed, all the edge cases have been assumed away, and all the structure has been flattened to fit on a page.

Readers go from the book to a real project and immediately encounter the things the book pretended did not exist: errors, partial reads, concurrent access, resources that need to be released even when something goes wrong. The gap between the book’s world and the real world is where most learning actually has to happen, and the book abandoned them there.

Real code is harder to write and harder to typeset. It is also the only kind worth studying.

They Do Not Comment on the Output Link to heading

A close cousin of toy code: the book runs the program, prints the output, and moves straight to the next listing. The output sits on the page as proof that the code compiles, not as something the reader is meant to understand.

But the output is often where the real lesson lives. Why are the goroutines printing in that order — or in no order at all? Why is that floating-point result slightly off? Why did the second run produce different numbers from the first? A reader staring at the output has questions, and a book that does not answer them has wasted the most teachable moment it had.

Showing output without interpreting it is a missed opportunity dressed up as thoroughness. The few extra sentences that explain what just happened, and why are frequently worth more than the code that produced it.

They Chase the New Link to heading

A book published in 2024 about a framework released in 2023, covering features added in a point release in 2024, will be partially obsolete before the print run is finished. The authors know this and write anyway, because the market rewards novelty.

The books that last are the ones built on things that do not change. Stevens' Advanced Programming in the UNIX Environment was published in 1992. It is still in print, still assigned, still correct in all the ways that matter. The system calls it covers behave the same way they did thirty years ago, because the underlying ideas — processes, files, signals, sockets — are stable.

If you are writing a book about a tool, write about the tool’s ideas, not its current syntax. Syntax changes. Ideas do not.

What a Good Technical Book Does Link to heading

It teaches you how to think, not just what to type. It has opinions and defends them. It is as short as it can possibly be while still being complete. Its code examples are honest about error handling and edge cases and it explains the output instead of just printing it. It is built on ideas stable enough to last a decade.

That is a high standard. Most books do not meet it, including some of mine.

The gap between a book that is published and a book that is genuinely useful is exactly the gap between covering a topic and understanding it well enough to know what to leave out.

If you are writing a technical book: have an opinion. Cut everything that does not teach. Write real code. Build on ideas, not APIs.

If you are reading technical books: the ones worth your time are short, opinionated and built on fundamentals.