Noel Rappin Writes Here

For Example

Advice, Examples, Technical BooksNoel Rappin2 Comments
Having shifted from editing on the book back to actual writing for a few new chapters, I'm back to obsessing about examples. (The book, of course, is Rails Test Prescriptions coming soonish to a bookstore or computer screen near you. Tell your friends.)

I feel like I spend way more time obsessing over whether I'm picking good examples than the question actually merits. Or to put that another way, I'm pretty sure there's a difference between a good example and a bad example, I'm much less sure there's a difference between a great example and a good example.

Back in the day (the day, in this case, being sometime in 1997...), I used to read a lot of education and cognitive science studies about how people learn, react, that kind of thing. Overgeneralizing wildly, the studies generally fell into two piles. One set took place in the lab and precisely targeted a specific hypothesis, but under lab conditions with dubious relevance to reality. The other set took place in a real, long-term setting, but with so much complexity in the setup and data, that it was unclear what conclusions could be drawn.

I feel much the same way about technical examples -- either you pick something abstract that covers the immediate ground with the risk of not making it clear how to apply this feature to a real application, or you show a real application and there's so much other stuff to cover that the immediate point can get buried in all the minutia.

I'm not sure if it's just me, or if other tech writers feel the same way, but there's something so attractive about the idea of writing a book around a single example that gets progressively more complex. So here's the thing about using that kind of extended example: it's really kind of hard. And the one time I tried it, I'm not sure it was worth the added effort.

When I started Professional Ruby on Rails, I had two things I wanted to try with the books structure: I wanted as many of the code examples as possible to be written test first, and I wanted to write the book as one extended example. The original pitch to Wrox for the book, in fact, was that it was going to be kind of a "I've learned Rails, Now What?" book, covering a bunch of things that "every" site would need to handle, like authentication, or whatnot.

The testing part worked great, I thought, but the example quickly became difficult to deal with. In essence, what I needed was a potential web site that had a) RESTful controllers, b) users, c) a search and tag cloud, d) a legacy database, e) some Ajax, f) sends and receives web service calls, g) internationalization, and h) graphic manipulation. Plus, there isn't any other complicated stuff that might have to be explained. It quickly became clear that while most sites have most of these things, putting all of them in one sample was going to be a bit of a stretch.

The site I chose, a social networking site for soup recipes called SoupsOnLine, actually worked for most of these, though the legacy database chapter is super-forced (and acknowledged as such in the book). Also, given that I spend about five pages in chapter one parsing recipe lines like "2 cups of carrots, chopped", it's possible that I was overcomplicating things just a touch in spots.

With that out of the way, I can get back to what I thought was the point to this way back a week ago when I started it...

If you are writing examples for a blog post, article, technical book, presentation, or whatever, keep these things in mind:



  • The goal is clarity. Make the example as simple, direct, and to the point as you can. This implies that you know what the point of each example is.



  • If the example is brief, you usually don't need any context beyond the code snippet you are presenting. Something like, "this is how you would use Blue Ridge to test default text in a search box. Your tests might look like this." A complicated, real-world context is only needed when the complexity is actually the point.



  • In most cases, It's best to keep the background details as abstract and minimal as possible, to keep the focus on the point. This implies that you know what the point of the example is...



  • The classic structure works. Introduce a code sample by explaining its purpose, "The following snippet shows how to use ActiveRecord to make banana muffins." Then show the snippet. Then walk through the snippet in detail, "In line one, the flour is retrieved from the database, to be mixed with the associated bananas in line three."



  • And I may have just violated a rule in the previous bullet. You should only take the funny so far in an example. It's okay to have something clever to help the example stick, but at the point where your pun gets in the way of the clarity of the example, its not worth it.


  • In general, you should explain a little bit more than you think you should. Couple of reasons. One is that, almost by definition, you have a different perspective on the material than your readers, and it's easy to forget the early steps that you may have learned months or years ago. Another is that different people will connect with different things, and the more ways you present information, the more likely a reader is to get it. I also feel that it's difficult (not impossible) to over-explain a point in a technical book -- in this kind of book readers who get it will often just skip ahead at that point.



So? What kind of examples help you out?