use Perl

I recently reviewed a chapter-draft for a book. I do that a lot, and try to offer insightful advice; but this time part of the advice was so generally useful that I'll excerpt it here:

[...] And finally, there are very many new concepts being introduced in chapter 9. To use a simile: [This subject] is like a foreign language; on top of its basic grammar and lexicon, it has it has its own idioms, its own strange conventions, its own little traps. And in Chapter 9, it's like you're taking a reader that can barely deal with "Voici mon ami Bobby. Il aime jouer au baseball!" and presenting him with "Il est beau comme la rétractilité des serres des oiseaux rapaces; ou encore, comme l'incertitude des mouvements musculaires dans les plaies des parties molles de la région cervicale postérieure; ou plutôt, comme ce piége à rats perpétuel, toujours retendu par l'animal pris, qui peut prendre seul des rongeurs indéfiniment, et fonctionner même caché sous la paille; et surtout, comme la rencontre fortuite sur une table de dissection d'une machine à coudre et d'un parapluie!".
It doesn't help that you annotate every word ("rongeur: rodent") -- it's still too much new complex stuff at once.

When we write a book, our first instinct is to assume that it's for people who want to understand every detail of what we're discussing so that they can master it completely, and we to that audience. But a book really has two audiences (with degrees of overlap): people who want to master the subject matter, and people who want to more or less skim the text and every once in a while see an example in the text and say "THAT! THAT'S what I want! If I change one bit of that, I'll have exactly the program I've wanted for years!". And you have to serve both audiences. Currently you're not serving the second audience (the "skimmers") well; more and better examples can fix that.

Back to the foreign language metaphor: say that it's time for your book to discuss the very common verb that means "want". You surely have to demonstrate how to conjugate it in the present and in the past-imperfect, its two most common tenses. You show it in a grid, for reference, and then with example sentences. ("I want pie. Does Jack want pie too? You wanted some, but now you don't want any", etc.) Now, the people who want to master things also want you to point out that the imperfect forms of every verb are based on the "they"-present form, minus the "they"-present suffix, and plus the appropriate imperfect suffix. So you tell them that as an aside, and they're happy.

But the skimmers don't care. What wakes them up is when they see all the good examples. "AhHAH, that's how to say 'you don't want any', with that weird contraction for 'not any!' If I change two things, I know how to say 'I don't want any!', a very useful phrase when I'm in Paris and the waiter offers me /escargots au lait/ or whatever. And I know how to turn it into 'do you want any?', which is useful too...". So the skimmers learn almost exclusively from the usefulness of the examples. But if your textbook is as full of useless examples as one of mine was ("The cows that were sick, are now dead" was one I remember from a chapter on relative clauses), then the skimmers become VERY UNHAPPY.
(In moments of occasional and total desperation, one can resort to examples whose total absurdity somewhat masks their uselessness: I remember teaching a certain kind of reflexive verb using examples like "they all shaved off eachother's eyebrows and threw eachother down a well. Let's throw eachother down a well, too, after having shaved off eachother's eyebrows!")

While I understand the perspective of someone who wants to master [this subject], I have to admit that I'm with the "skimmers" here, and I want more examples that make me wake up and say "I want to take that, change two things, and then I'll have something I've been after for ages!" In short, I don't want to master [this subject], but I want to learn the 20% of [this subject] that will have me doing 80% of the things I'd ever want to do. And as I ask around among other programmers, I find that I am solidly in the majority on this point.[...]