Skip to main content

Do you really want long running examples in tech books?

Posted by timboudreau on July 6, 2009 at 1:39 AM PDT

I've coauthored two books about programming, and in both I heard the complaint (paraphrasing) "There wasn't one cohesive example that was built up chapter-through-chapter."

There's a reason for that. Back in the 90's, I did a lot of programming in Delphi, and bought many hundreds of dollars worth of books. By far the best, for my purposes, was Delphi Component Design - and the reason I loved it was that I could pick it up and open to any page and learn something, without having to read and type in ten preceding chapters of code to have it make sense. I've tried to channel that book in my technical book writing since, because it was so useful and straightforward.

I'm currently reading (well, really, skimming, skipping around in and finding what I need), Eelco and Martin's Wicket In Action, and enjoying it for exactly the same reason - although they do have a long running example - Cheesr, the cheese web site. But you can open it up to any page and learn something that's probably relevant to what you're doing.

I've always thought of the book-length-example-application as a book killer - every book I ever bought that took that approach was one I wished I never wasted the money on. I'm never going to plow through a 300 page book and write every line in its code blocks - I want the why, not the how! If I know the former, the latter is icing on the cake.

I can't say my tech writing is great - I probably spend too much time on the why. My grandfather was one of the developers of the dial-telephone (a big deal in 1930 or so), and had me wiring up circuits when I was 9. He taught me that everything in the world was understandable - electricity is just water moving through a pipe - AC current is just moving the water back and forth instead of pushing it along. Whenever I'm trying to teach something, I try to think how he would have taught it to me and channel that - above the realm of quantum physics, there's always a metaphor. Once you've got the metaphor, you've learned at least one way to fish, and that beats being handed a fish (unless you're into that sort of thing :-)).

Do people really want tech books with examples where, if you skip the first chapter, there is no way to get oriented? Or is it just an expectation of professional publishers and reviewers who never actually will follow the book through anyway?

I spent the last half of the '90s working for tech writing companies that got paid a fortune to produce training materials I had to glue together (spend nine months writing a [Netscape 4/ IE2) cross-browser-compatible javascript emulator of a menu-driven DOS app which is really three apps glued together by a menu, some of which do and some of which don't know what a mouse is sometime - it really doesn't matter how much you're paid, suicide still looks like a good alternative).

Most of them were well structured, well designed, and guaranteed that nobody would ever learn a darned thing from them - but that wasn't the point - the point was that the company laying out the unbelievable cash for us to create this garbage was getting an even more unbelievable break from their insurance company if they could prove their managers were "trained." In other words, there was this whole chain of lies that led to me getting paid to produce utterly worthless crap. All of which would have been fine, except that I wanted my life to have some meaning, so I moved to Prague and went to work on NetBeans :-)

I'm just wondering if the book-wide example, where you start in chapter one writing the login page and end up with your very own at the end actually teaches you how to write anything but It's always seemed like a cop-out to me - I want to know the why's, so when I have I problem I can intuit the solution - and that's how I've always tried to write. It seems like the tech industry rewards rote instructions more, and that's a pity.


Related Topics >>


I personally think a lot more attention should be given to character development and the story arc, plot twists etc.

I don't like lengthy fictitious examples at all. I never read them. The only thing I care about are insights gleaned from actual code bases. There are masters of the art out there and I want to know how they did it. It doesn't always have to be beautiful code. If you teach people some theoretical device it is as important to know when not to use it. You have to compromise to achieve your goal. That's why people love "Effective Java", "Java Puzzlers" and "Java Performance Tuning". All of them are reality checks. These books provide guidance: "This is one way to do it, this is another. This is how you should do it. And here's why..."

To me, the book-wide example is a literary device you may use to keep the book cohesive in case you need to cover different topics that may otherwise be unrelated to each other. So, instead of feeling like you are jumping from place to place, you lead the reader more naturally and logically.

Some books, like cookbooks and reference manuals, are _by design_ not cohesive. I really doubt that a book-wide example there is useful... (though if tasteful can be entertaining). Some other books, like one that concentrate on a particular API or product, may have already a central topic that already brings the book together.

In the end, like all literary techniques, I don't feel it's either good or bad... and it's pretty much to the author to use it well (or make a disaster of it). But if the reader after reading the book can't really apply the knowledge to other contexts, either the book has no content or the reader is not that smart... and changing the style of the book won't solve either.

Both approaches are needed. Jason Rudolph's book on Grails ( provides a sample that is carried throughout the book. It's a great book. I recommend it. But if there were no other books on Grails, that would be a problem, because the other books, which are user or reference oriented, are just as badly needed.

When I read tech books there's always that feeling that I miss the 'only-a-chapter-long-example' or the 'one-example-for-the-whole-book'. I agree that it helps a lot to just be able to open the book, pick a chapter and learn how to use what is discussed in the chapter. But many books aren't just about fragments of technology, most books are about the many aspects of just one topic/technology/framework, and for me in many cases it matters to know how everything fits together. I want to learn the separate aspects, but also how to use them together. Pretty much all books do just one of both. As if the author didn't spend enough time to think of a sample that allows for being used throughout the book, but takes one fragment of information and sample with it at a chapter. Iwan

Having written a few programming books and read many more, I firmly come down on the "short examples are better" side. Whenever I see a book that drags one long example through multiple chapters, I groan. The example is usually artificial since the author feels compelled to pile on the material from every chapter. It is usually tedious--most real world code has lots of tedium--and that makes it harder to see the interesting and important parts. It is often confusing--when the author has us go back and forth between various versions of each component, and we have to keep track of how the versions evolve from one chapter to the next. I am ok with a capstone chapter that contains a few longer examples (but preferably not one monstrosity that attempts to "tie everything together"). For the rest of the book, I really want short and independent examples. Fabrizio brings up an interesting point--could a book dissect an open source project and use that to teach how to write "real world" applications? That would be great, but unfortunately when a book about a new technology comes out, there aren't many projects that use it.

Why limit to one or the other? To me the best books for learning provide both short, runnable programs that demonstrate the specific items being discussed in a section (ideally, even more granular than chapter -- as you note, something useful on every page) as well as an example that spans the entire book that ties everything together.

I have read many programming books and have found the ones that had a program span the entire book much more difficult to follow when starting out. The short programs that demonstrate a technique or bit of api are much more helpful for first time learning.

I think there's a twofold answer to be given. First, the "random-access", readable books you were talking about are necessary. If you are learning a technology from zero (or almost zero) you must be able to navigate the book at random, while you're also experimenting with your own code, or code taken from blogs etc. I would classify this kind of books as "introductory", but the wording is not good enough as they can include advanced topics as well. So, let's keep them and let's go on with writing them. But - for sure, there's the point that many small examples are good for learning the APIs, not for building an architectural perspective which includes some real world concerns, like dimensioning etc... Of course, the other point is that since I'm talking of "real-world", the subject of the book shouldn't be an academy, but a real world application. Of course, since you're describing it, it must be a read world, FLOSS application ("must" is a bit forced, but you get the point). I would surely buy and read such a book (*after* reading the "random-access" ones).