How to Write a Technical Book (Part 2)

Following up on the first post in this series, here are a few more tips for anyone thinking about writing a technical book.

  1. Read, then write. Go through your two favorite technical books and make notes about what their authors have done well. Doing this will give you some ideas for your own book, but it will also help you become more conscious of your writing—in musical terms, help you learn how to listen to yourself while you’re playing. I learned a lot by reading Brian Kernighan and Jon Udell, but your tastes may vary.

  2. Do the diagrams on a whiteboard first. It’s faster and more flexible than any computer drawing tool (though I admit I don’t have much experience with fingertip sketching apps for tablets). The only downside is that you can’t save a whiteboard drawing and reload it later, but they’re so fast to re-create that that’s not an issue.

  3. Don’t write a general introduction unless you’re going to be one of the first two or three to market. Instead, focus on a particular aspect (“Python for Web Scraping”) or a particular audience (“R for Sports”). Your potential audience may be smaller, but you’ll reach a much higher percentage of that audience, and a focused book is a lot easier to write.

  4. Don’t try to be funny. Very few jokes are funny the second time you hear them; even fewer can stand a third re-telling unless they’re very, very dry. And on a related note, please don’t use exclamation marks: what you’re writing probably isn’t surprising, and certainly won’t be the second time around1.

  5. Avoid banal advice. Few things are as frustrating to the reader as sentences like, “You should carefully consider users’ needs,” because no sensible person would recommend the opposite. If you can’t provide a checklist of specific things to consider, or a scenario to give the reader insight into how you think through that class of problem, you’re giving them the intellectual equivalent of junk calories.

  6. Don’t try to compete with the internet. Reference manuals were invaluable to me forty years ago, but serve little purpose when the world’s knowledge is just a click away. You add value by explaining the how rather than recapitulating the what, so do that.

  7. Check your facts. It doesn’t matter how well you know your chosen subject—something will have changed since the last time you looked. And even if it hasn’t, it will in the year or more it takes you to write your book.

  8. Automate, but proofread. This is the technical author’s equivalent of “trust, but verify”. I can re-run all of the examples in my latest book with a single command and capture their output and insert that output in the manuscript, but I still have to re-read the discussion around those examples to make sure it hasn’t fallen out of sync.

  9. Enlist at least two people to do detailed reviews. Lots of people will do cursory reviews or give your manuscript a single careful read; people who will look at half a dozen sets of changes and see what’s actually on the page in each are worth their weight in rubies.

  10. Stop and ship. Your book will never be perfect. It will probably never even feel finished, any more than software does. Ship it anyway.

1. And remember: nobody reads footnotes.