Jelly Stains and Web Masons
From Mark Bernstein's entry on Practical Prototype and script.aculo.us:
When chemists consult a volume about professional chemical technique, or when surgeons reach for the latest update on neuroanatomy, they can usually find a book that isn't couched in terms of silly examples and jokes. So can poets, mathematicians, and geologists. For some reason, though, it has become the accepted practice that language manuals should spend lots of time with silly, self-deprecating jokes, and that their example applications should be breakfast loggers and fantasy football leagues (or, conversely, payroll programs).
As an tech author with just a few books under my belt, Mark's take on Practical Prototype and script.aculo.us struck a bit of a sour note for me, because I'd like to work on making my tech writing more entertaining than not. I think that's a good thing, but I'm willing to be convinced otherwise.
I think the issue is that there are different meanings for "professional" when it comes to the web. There are web scientists and there are web masons. Web scientists pursue fundamentals and disambiguations, while web masons are busy building the next micro-site for the new product release from the almighty client. Many web scientists are also computer scientists and many web masons are also web scientists—but most web masons I've known come from creative liberal or fine arts backgrounds.
Though, for what it's worth, even amongst computer scientists there's still a tradition of leaving room for jelly stains and other oddities. This seems to be the sort of thing Mark acknowledges with dismay. ("It’s not fair to blame Mr. DuPont for the general vice.")
Is playfulness in literature just a computer science thing? I'm not a chemist; maybe chemists just don't like being funny in writing, or maybe their jokes are more subtle.
In any case, I think the "practical" genre of tech books is aimed at people who want to get something done, aren't interested in or have little time for context or background, yet wouldn't mind being entertained during the course of weekend tinkering and self-education.
So, a good book. But take out the jokes, trim back the sample code (or dispatch it to the Web site where it makes more sense), and give us to professional perspective, and everyone is going to be much happier.
The guidelines with which I'm familiar for tech books in the "practical" or similar genres include advice such as "show, don't tell". They also suggest that, although sample code should be made available online, the author should compose the book assuming that it's a standalone product. Web sites and CDROMs with code often vanish, but a bound book remains stable—which is especially useful on a cross-country flight without net access. Professional perspective is of course a desirable thing to work into the prose, but job #1 is to illustrate the right way to do things through running code.
I'd really be surprised if many readers have heard of Self or C++/STL or have much of a grounding at all in computer science or programming language fundamentals. Having these fundamentals would of course help web masons get a deeper understanding of the technologies that make the job possible, but the pragmatic rewards tend not to make up for the effort involved.
So, to sum up, the purpose for this entry isn't to beat up on Mark Bernstein. He's written a great deal of prose and code that I respect, so his opinion is interesting to me. Rather, I've tried to express my own understanding of this writing market, and hoping I've aimed at the right goals.