zerosum dirt(nap)

evolution through a series of accidents

zerosum dirt(nap)

Note To Self (Good Examples Are Hard)

May 03, 2008 by nap · Comments

The single hardest thing about writing a book, I’ve decided, isn’t the writing part. It certainly isn’t the technical part either. I don’t mean to downplay my own skills or those of any other technical author, but the truth is that you don’t have to be a guru to write a fantastic book (it does help, of course).

The key to writing good book material is being able to show people how to do things while keeping them entertained. That means coming up with examples that tread the line between being practical, being appropriately demonstrative, and being correct. Good examples are the hard part.

When developing an example, you’re trying to come up with something that has the following characteristics:

  • It’s interesting. That is, it’s worth writing about in the first place. No one wants to read another blog post creation example (unless there’s something unusual about it). BORING.
  • It represents best practices. You’re an author. You have to be right. Or at least able to competently defend your implementation choices, anyway.
  • It illustrates those concepts that you’re trying to write about. This should be first point, rather than third. See what I mean?
  • It minimizes focus on those elements that you are not writing about. That is to say, we shouldn’t spend a lot of time talking about fuzzy bears, even though there are many different types of fuzzy bears, six species of which are listed as vulnerable or endangered by the World Conservation Union (whose headquarters are in the scenic Lake Geneva area of Gland, Switzerland).

bears!

The last point is a tricky one, but it’s important. You have to cut corners when creating good examples — but not the important ones or the ones that would prevent it from representing best practices. If you’re trying to illustrate, for example, how to build a tag cloud, you don’t want to spend lots of time on the CSS for making it pretty. Leave that to the CSS books.

If your example involves video transcoding, and the point is to illustrate the use of a message queue, you’re going to be really tempted to spend an extra 2-3 pages on certain format discrepancies or operational edge cases but DON’T. It’s interesting, sure, but if it’s not central to what you’re currently trying to demonstrate (message queues). You must resist.

If your example is a simple web service for sharing geographic location data and you’re using a bunch of RESTful conventions, make sure to explain the basic concepts. But don’t write a dissertation on REST vs SOAP. And don’t worry about responding to formats that aren’t part of the main example.

Just because it’s how you’d do it in a real-life project doesn’t mean it’s how you’d write about it or explain it to others. Keep it simple, lively, and (as Gold Five so succinctly put it before crashing his X-Wing) stay on target.

blog comments powered by Disqus