Index cards as bricks
Good books always read as if the author sat down with perfect knowledge of the topic and then just said it on paper. Who knew authors litter their office floors with index cards, and their garbage cans with sketchy early versions of chapters. All in a quest to solve a problem that, ironically, the author doesn't have: the reader's lack of knowledge and context.
I spend a lot of time and energy organizing the material in my books. I draw big dependency diagrams on white boards; I make index cards for various topics and then lay them out on the floor in various experimental orders; I write sketchy early versions of half a dozen chapters to test if the material flows correctly. The ordering of material is a central problem in writing a programming tutorial, and I struggle to get it right. I want each chapter to progressively build on the last, like bricks in a wall of knowledge.
A large part of the difficulty in building the reader's "wall of knowledge" is a problem of getting the hierarchy right. There must be a buildup of logically dependent pieces -- the epistemological equivalent of a game of Tetris. Some pieces are especially crucial to the goal of completing the wall:
In any book I write, one of my constant goals is to demystify the [topic]. Anything that seems like "magic" is a target for me.For "[topic]", he actually said "API", but I like this as more general advice for a writer: to maximize the value of your book, make accessible that which was previously least accessible. A corollary I'd like to note: if the topics are already sufficiently accessible, then a new book isn't worth writing.
Petzold regrets the lack of screen shots in ACM, but I have to wonder how much longer the book would have been with them. As it is, I'm on page 55 of 976.