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"
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?
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 amazon.com at the end actually teaches you how to write anything but amazon.com. 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.