Dear Log and Folks,
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.[...]
Re:Writerly Advice
ziggy on 2002-06-24T13:21:19
There's a self-perpetuating meme at work there. Because other books are thick and narrowly focused, new titles need to be thick and narrowly focused as well.Looking at the computer bookshelf you see the page count increasing as the subject matter becomes more specialised.I was approached by a respectable publisher last year (who shall remain Not O'Reilly (tm)) to write a book on some reasonably new and fashionable topic. In the preliminary discussions, the editor talked about writing a book that would be at least three inches thick. That was literally the first characteristic of the book we discussed -- before even the depth or breadth of coverage (which was left unmentioned, come to think of it).
After talking about the 3-inch minimum shelfwidth, we also talked about the standard tricks used to get that width: thick paper, wide margins, 14pt typefaces.
The rationale? Since everyone else is doing this, we need to do it as well, just to get customers to read the spine at the bookstore[*].
Oh well. At least some publishers have the gumption to print a 200-page book when 200 pages is enough to cover the subject...
*: How does the shelf width tempt book buyers at Amazon.com or Bookpool? I never figured that out...
Re:Writerly Advice
TorgoX on 2002-06-24T21:18:22
Tech publishing, and publishing in general, is only as good as it has to be, and often worse.Re:Writerly Advice
koschei on 2002-06-25T00:36:08
Darn TCP/IP book I had to buy (textbook). Fattest book I own, thick pages, massive font, awful index, and I'd be surprised if, were it retypeset like an ORA, it were larger than the Perl DBI book. It's worrying, quite worrying.Re:Writerly Advice
TorgoX on 2002-06-24T21:44:18
I think the specialization is another question altogether, distinct from the topic of having examples that cater to all kinds of readers.I think the specialization is an attempt to get at subaudiences, and it's not inherently bad (if we mean the same thing by "specialization").
