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?


Advice, PragProWriMon, Technical BooksNoel RappinComment
Pragmatic wants November to be PragProWriMon, something of the non-fiction alternative to NaNoWriMo, or National Novel Writing Month. It's a great idea. The best way to actually write anything is to get in the habit of sitting down and typing. Conversely, the best way to stop writing something is to break the habit, even for a couple of days.

There are other places to go for inspiration on sitting down and writing (I'm kind of partial to Merlin Mann's epic about making the clackity noise). But I do have a couple of disjointed things to say about writing technical books for programmers.

Write about something you'd love to learn more about

I'm completely confident in the following statement: you will need to learn new things in order to write a complete technical book. Even if you are the lead maintainer and undisputed overlord for eternity of an open source tool, there's going to be something going on in the ecosystem that you're going to need to know more about when the time comes to write about it.

I'm also completely confident in this statement -- if you are willing to learn new things, and learn them quickly, you don't need to be the lead maintainer and overlord to write a good technical book on a topic. (Though it does help tremendously to have a trusted super-expert as a technical reference.)

Pick something that you are genuinely curious about and that you want to understand really, really well. It's painful to write even a chapter about something that doesn't interest you.

I'm sort of a test subject for this because I've had wildly varying levels of expertise on the subjects of my books when starting writing. For the Jython and wxPython books, I was brought in to help out a co-author who was the true technical expert and I only had a little bit of experience with either one going in. In contrast, the Rails test stuff I'm writing now really is the stuff I've been working on for the last few years.

The main weaknesses of not being a true super-expert going in are a) it's more work and b) the nagging feeling that you're making mistakes that you can't see. But there's an advantage, too. The closer you are to learning the material for yourself, the more sympathetic you are to a novice's struggles to control the material. The key is being able to explain the material clearly and interestingly, and being clear about what you know, what you think, and what you struggle with. I would totally buy a book like "Watch a Ruby programmer struggle to learn Scala" -- I think that would be an interesting way to learn from somebody else's mistakes.

Have an opinion

"A movie is not about what it's about; it's about how it's about it." -- Roger Ebert

"One of the operating assumptions of this book is that you either own Macmillian's The Baseball Encyclopedia or aren't interested in what it has to say; in either case you don't need me to tell you what an outfielder's assist totals were." -- Bill James

I love that random Bill James quote so much that a paraphrase of it tends to sneak into my books somewhere (along with a reference to Scott McCloud's Zot!). The point is to have assumptions -- you can't explain everything. It would have been easy for James to clutter his book up with even more numbers that most of his readers already knew or could look up, but he elegantly sidesteps that problem.

My Jython book suffers because we never really decided whether it's primary audience was Python programmers or Java programmers. The wxPython book is pretty clear in assuming the reader already knows Python. (We actually wrote an introduction to Python, but it was too short to be useful and ultimately cut it). The Rails testing book is clear both in assuming that the reader already knows Rails basics, but also in assuming that starting with the Rails core tools is the best way to get introduced to testing Rails programs.

You have opinions about the tools you want to write about -- how to use them, when to use them, when not to use them. Your book needs your opinions (even, I'd argue, if it's got a strong reference component) otherwise it's something anybody could write.

That's long enough for now.