Rails Test Prescriptions Blog

Keeping Your Application Healthy Since 2008

For Example

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?


2 responses to “For Example

  1. yachris November 14, 2009 at 10:13 am

    You might want to ask your readers for books with awesome examples… maybe there’s something to be learned from them 🙂

    Here’s one of my favorites: “The Rails Way” by Obie Fernandez. His examples are short, to the point, and show the feature/technique clearly.

    It’s worth noting that beginners use examples as a way to learn something new, but experts use them as a cookbook… I might think, “Okay, I know that I can do the nested routes thing, but what’s the syntax look like?” long after I know that they exist, and what they’re good for. So an ideal example works for both cases.

    • noelrap November 14, 2009 at 11:32 am

      @yachris — that’s a really good point about experts, and it’s actually how I use my own books after they are out. There’s always some piece of syntax that I specifically put in I books so that I know there will always be a place I can find it. (In the Wrox book, it’s the table of standard RESTful routes).

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: