Sunday, March 21, 2010

Arghhh

Okay, time for a minor pet-peeve. If you're going to include a DVD with a book that includes sample implementations of concepts you MUST make it a requirement that people include some kind of sample for EVERY CHAPTER. I realize that's an additional burden on the author, and the editor might go through hell trying to wrangle all those chapters. Oh, and no doubt there are concerns about code quality, and lots of experimental code tends to be a little spaghetti-ish. But frankly I'll take anything if it can show me a sample implementation I can just quickly rip apart and get to the meat of.
Implementation details are often left out, or left unclear, or just left as exercises for the reader to discover. Given the purpose of a "Gems"-style book - which is to provide a reader with insight into *implementation* details and not simply to get some idea published - it's important that the reader can walk away with as clear an understanding as possible.

2 comments:

  1. Hi Jon,

    It's not always that simple though. For example, I absolutely did NOT want a CD with my book, because providing sample code is not what the book is about! The publisher insisted and eventually I gave in and the CD ended up with a minimum of files because the CD was never intended to be there in the first place!

    But, yeah, if you're talking about a book that is effectively intended to provide a cookbook solution, then I agree.

    ReplyDelete
  2. Sure, not every book should have one, and really not every chapter in a Gems book should have one (some are really very clearly pure theory). But if you're going to mention and use a toy sample to implement the idea in a book that's all about practical implementation (ie, most Gems) and not a dense theory book, you really have no excuse not to provide the source for it so people can see how it works.

    ReplyDelete