Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

TorgoX (1933)

TorgoX
  sburkeNO@SPAMcpan.org
http://search.cpan.org/~sburke/

"Il est beau comme la retractilité des serres des oiseaux rapaces [...] et surtout, comme la rencontre fortuite sur une table de dissection d'une machine à coudre et d'un parapluie !" -- Lautréamont

Journal of TorgoX (1933)

Saturday June 22, 2002
09:46 PM

Writerly advice

[ #5870 ]
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.[...]

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • If only more people followed your advice... Looking at the computer bookshelf you see the page count increasing as the subject matter becomes more specialised. Do you think that authors cover everything in detail because that takes less skill than determining what to include/exclude? Do book buyers relate page count to value?
    • Looking at the computer bookshelf you see the page count increasing as the subject matter becomes more specialised.

      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.

      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 wo

      • Tech publishing, and publishing in general, is only as good as it has to be, and often worse. [greenspun.com]
      • 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.
        --
          ---ict / Spoon
    • 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").