0xDECAFBAD - Tag: books

Jelly Stains and Web Masons

2008-10-29T14:42:23+00:00

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.

How does Prototype+Javascript relate to other languages — C++/STL, say, or SELF? What, precisely, are the semantics of the key methods? I don't need the inevitable chapter 1 pitch for the wonderfulness of Javascript and the badness of MSIE, but it might be a good place for a quick summary for the pros. Call by reference • no pointers • primitives are objects • everything has a prototype slot • parens() do this, braces {} do that, brackets [] do something else • single and double quotes are different. Kernighan & Ritchie did this so well in C, and it’s not like we’re not familiar with their example.

I'd posit that most in the audience for "practical" tech books are entirely unfamiliar with Kernigan & Ritchie and haven't touched a line of C source code. Most of these readers have probably tumbled down the slope from HTML to CSS and finally to JavaScript in order to get something interesting to happen in a browser—and usually while under an unreasonable deadline.

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.

Archived Comments

Mark Bernstein
2008-10-29T16:51:59

I'd settle for a better class of joke!

On tech content, doesn't it annoy you that it's hard (or impossible) to find a book about a Web framework or language or facility that takes advantage of what you already know? One that doesn't assume you've never seen a language before?

I understand that publishers want the book to appeal to everyone. But it's not that the reader needs to know Kernighan: you know, right? So you know that it's entirely practical to tell a colleague pretty much everything she needs to know about a (famously tricky) new language in one chapter, starting from Kernighan's example 1 -- the original "Hello, world".
Aristotle Pagaltzis
2008-10-29T20:28:27

I think part of the difference is in the subjects themselves. Programming deals with pure thought stuff, yet at the same time attempts to model concepts from the physical reality. In contrast, science textbooks deal with intrinsically tangible stuff, while mathematics textbooks deal with the abstract for abstraction’s sake. The temptation to offset the potential dullness of pure thought stuff by using it to model goofy examples is obviously high.

Corroborating my theory would be the fact that elementary, low-abstraction maths books tend to bring up oddball examples too – eg. consider the sorts of things used to illustrate the rule of proportion.
Dave Dash
2008-10-30T00:53:54

Most books about web technology are meant to have a shelf life of a few years. They aren't reference guides, and they aren't meant to stand the test of time.

PHP, Python, Prototype, etc will all change.

Because of this, they can employ jokes and real-world examples. Jokes make reading the content enjoyable. Examples are step by step instructions to creating something useful.

If those aren't needed there's always reference guides.

I don't publish books, but I do write tutorials on my blog on occasion. One pattern I employ in my blog the "executive summary" pattern. I start with the take-away, the code snippet, the answer if you will. Then I spend the rest of the post (behind the fold, if you will) explaining the answer and interjecting my style.

I like doing this, because it's what I would want. I want to know the answer, and then I can read on for some backstory... rather than having to separate the wheat from the chaff.
Andrew Dupont
2008-10-31T03:30:21

I'm quite familiar with the trend Mark's talking about. And I agree that it shouldn't count against me or my book, but perhaps I'm a bit biased there.

Three things.

First: my book reads the way it reads because that's how I write. The process of writing the thing was torturous enough that I doubt I'd have finished it if I subjected every word to the scrutiny of a hypothetical skeptical reader. I'm not good enough at the craft for that. I think that each author has to find his best angle on the material and write that way. Because there are many books and many publishers, it tends to balance out.

Second: my book covers two JavaScript frameworks built to simplify common tasks. Basic familiarity with JavaScript is assumed. Right away that's a step away from the theoretical and toward the practical. I think tech books are best when they stick to one or the other, rather than try to drift between them.

Third: the book Mark wants has already been written: JavaScript: The Good Parts, by Doug Crockford. Doug's style is dry and academic, but also direct and substantive. If I tried to write in that style it'd be only a pale imitation.

Anyway... the "quirky" trend, I agree, can be tiring. As it applies to my book, the sticking point seems to be whether I'm actually funny. Readers of this weblog will simply have to buy the book to find out. It's several hundred pages long and has a fresh, earthy "new book" smell.
l.m.orchard
2008-10-31T03:47:37

@Mark: Yeah, these days my first impulse is not to reach for the latest book on a new technology like a web framework or new language. I usually head straight for the source code or start soaking in whatever documentation may be lying around on the web.

I suppose I could be a macho geek and say that's why I'm writing the books now—but to be honest I don't tend to get much out of practical programming books. They seem to sell, though, so I keep wondering if mine shouldn't be lighter or more fun, should I get the opportunity to produce more of them.

My first book was about half-and-half prose and code, with barely any screen shots to be found. I got to about equal parts code, prose, and screen grabs in my second—I thought that might make it easier reading.

The latest one doesn't have any jokes, but I tried to get straight to the core framework features and spotlight a few obscure magical bits. I worry if it might be a bit too dry.

But yeah, I do wish there were more (though maybe shorter) books that started from the assumption that I've got a CS degree and have tangled with a few languages and libraries so far. On the other hand, I do like having a sense for the author in a book—but that might be thanks to the fact that I read more blogs than books these days and enjoy the personal touches.
l.m.orchard
2008-10-31T04:05:01

@Andrew: Hey, thanks for dropping in for a comment! I can completely sympathize with needing to find a groove to handle how grueling producing one of these books can be—especially if you're more programmer than writer. (That's me, right now, anyway.) You need to get the best thing out there in the shortest amount of time, and find a way to get yourself to finish it.

At any rate, congrats on the new book, and I hope the cross-blog chatter sells a few more copies for you!

Books I've read lately

2006-01-19T16:21:59+00:00

Radio silence around here again. Been quite busy since Christmas, long hours at work and long hours at home. But, somehow, I've still managed to plow a decent path through the pile of books left for me under the tree.

So, I figure this might be a good time to mention them:

Burn, by James Patrick Kelley

This is an excellent mix of post-human future and pastoral retreat from same. It's just shy of novel length, but there's plenty of story here. And there are plenty of things not completely spelled out, but explained just enough to give a sense of a larger universe into which this tale is nestled. Also, don't miss the podcast reading by the author! That's how I found out about the book, after all.
First Meetings in the Enderverse, by Orson Scott Card

I'm always a sucker for an Ender story, and Orson Scott Card is one of my all-time favorite authors—even if I do think he voices some ornery political opinions from time to time and has a pretty unpleasant reputation. Some great origin material here, as well as the original Ender's Game.
The Crystal City, by Orson Scott Card

I'll be sad if this is the final volume. I'm pretty sure that the entire Alvin Maker series is a barely-concealed religious allegory, but that doesn't keep me from enjoying the heck out of this alternate history America. Whatever your faith or lack thereof, the struggle against the Unmaker is universal. That, and I'd like to think I strive to be a bit of a Maker, albeit mostly only in software.

I'm also starting on:

A Mind So Rare, by Merlin Donald

Just about 30 pages into this one, but so far I'm enjoying it. As opposed to a lot of the deterministic stuff about consciousness I've read in school and on my own—"You are simply a machine!"—this book would appear to use the same research to present a picture of the mind which in fact supports awareness and free will.

Archived Comments

Adam Wendt
2006-01-19T17:27:52

As far as I know The Crystal City will not be the final Alvin book. If you like Ender stories you may want to check out Intergalactic Medicine Show which should have a new Enderverse story in every issue (the first issue has a story about what Mazer was doing after his victory while waiting for Ender to show up)
Aneel
2006-01-20T02:49:42

You should take a look at The Mind & The Brain: Neuroplastiity and the Power of Mental Force .

Jeffrey Schwartz goes through the history of research surrounding neuroplasticity and covers his own research into helping OCD patients cope with their problems through conscious direction. I'm not through the whole book, yet, but he's contending that the consciously-directed, reshaping of the physical structure of the brain shows the causal efficacy of the mind. There was a hint earlier (I'm about half-way through) that he will broach quantum mechanics to find the actual phsyical forces involved.

It would be interesting to read what you think of A Mind So Rare, once you're done.
l.m.orchard
2006-01-20T03:42:18

Adam: You might be pleased to note that your recommendation finally pushed me over the edge of finally signing up for IGMS. I kept meaning to, and it hung out in a browser tabe for a long time after I'd first heard of it, but now I finally did it. :)

Aneel: Huh, that sounds like an amazingly interesting book too. On the wishlist it goes—thanks for the pointer. And I'll definitely have to ramble a bit more about A Mind So Rare

How to Hack RSS and Atom Feeds

2005-10-28T15:22:26+00:00

This article is an excerpt from the ExtremeTech book Hacking RSS and Atom. This feature explains what RSS and Atom feeds are and how you can build an aggregator, route feeds to your inbox and buddy list, subscribe to multimedia content, and more.

Source: ExtremeTech: How to Hack RSS and Atom Feeds

Woo hoo! Looks like the first chapter of my book has been excerpted on the ExtremeTech site. Check it out!

Looks like I need a new library card

2005-10-25T16:05:58+00:00

You know, I just realized that I haven't stepped foot in a public library since I graduated college.

You know what else I realized? Our local library has a great card catalog online, in which I've found everything I tried looking for. It even seems to have a queue / wishlist feature! Don't I feel behind the times? (Though, on the downside, they don't have a copy of my book. Damn, so much for egosurfing in the stacks.)

Now, if only they shipped books around like Netflix. But, I suppose it wouldn't kill me to talk to a few librarians. :)

Archived Comments

Tom
2005-10-25T16:40:51

Our library (http://kcls.org) does ship books around, at least to the branch of your choosing. Maybe yours too.
Tom
2005-10-25T16:47:35

Looks like yours does too: http://ibistro.tln.lib.mi.us/iBistrohelps/English/ineed_material.html
Matt Blackcustard
2005-10-25T17:01:20

If you request it they might well get it in for you. Get a couple of friends to request it as well and they certainly will...

That's the case at AADL, who also have an pretty good new website, complete with RSS feeds of your checkouts and requests, and librarian 'blogs' set up for news, recommendations etc: http://www.aadl.org
kellan
2005-10-25T20:24:05

I use my library just like Netflix, using the website to have all my books shipped to my nearest branch, and getting notified by email when they arrive. (that the nearest branch is only 3 blocks away helps maintain the Netflix-like feeling )

The library bcomes a convient shipping kiosk (which given that our local branch can't have more then 500 books, is really all its opitmized for anyway)

Be great to see a library system embrace this model, and start rolling out micro-branches.
David S
2005-10-26T00:42:04
I also discovered the wonders of the online library when I moved last year. They might not ship the books to your door, but as the others said, you should be able to get them transferred to a branch near you and get an email when they're ready. They'll even email you to let you know when they're due.

You could always donate a signed copy of your book to your local library as a thank you and encourage them to get the updated Sirsi system with RSS feeds.

Here are a few links you might find useful:
Andrew
2005-11-13T23:06:08

The SouthEast Michigan Library system has made me a believer again in the modern library. I already did manual searches now for books to be shipped to my local library instead of buying from Amazon, et al. Those greasemonkey scripts should be very nice.

Of course, the Royal Oak library (orig link) is currently closed for renovations. :p But then again, most of the libraries in the area were recently built/upgraded and each has a unique, and interesting thing to see - so I highly suggest a sojourn to the Livonia, Redford, and Northville libraries at the least.

DOM Scripting sounds like a fine book

2005-10-08T17:21:30+00:00

Flicking through the book, it does give the impression of being full of code. I hope that doesn’t scare off any potential buyers.

Source: DOM Scripting: The book has landed
This is one thing I'd worried about with my book, but on the other hand I always wanted to write for The Transactor. And what I wanted to write was a book I would've wanted to buy, if I hadn't written it.

By the sounds of it, DOM Scripting has turned out brilliantly. I'm looking forward to checking it out! It's described as a book targeted at designers versus coders—but a lot of times, it's easier to show-don't-tell with code than with prose.

Apart from those minor quibbles, I’m pleased as punch. I still can’t quite believe that I wrote an honest-to-goodness book. Some form of celebration is called for.

This is exactly how I felt, too. Congratulations, Jeremy! I'm going to have to pick up a copy of this book for myself!

Archived Comments

Jeremy Keith
2005-10-09T00:42:48

Thanks, Leslie. I think you can relate to how I'm feeling right now.
Warren Fischer
2005-10-09T10:51:38

This book makes sense in a clear, and consice way that most tech books don't. His examples are great, and his writing style is very readable. Thanks!

Hacking RSS and Atom is out!

2005-09-13T23:45:47+00:00

If you've been following along with me these past months, you might've gotten the gist that I've been working on a book. Well, lookee what landed on my doorstep late Friday afternoon--my author copies!

This package was actually supposed to have been delivered on Thursday. But, much to my consternation, I wasn't present to sign for the package. But now, I've got the surreal experience of holding a bound volume of around 600 pages with my name on the cover. And inside? There's all this stuff that once appeared on my PowerBook screen in MS Word and Terminal windows. (Oh yeah, and there're a few photos of my iPod thrown in for good measure.)

Funny thing is, this process started for me back in late December 2004. But, you'd barely know it, because--for whatever reason--I started off pretty cagey about the whole thing, and then plunged headlong into the effort. I did manage to make a quick announcement of authorship, but thereafter only managed to emerge for a few quick thought dumps.

I think part of my silence about things stemmed from a reticence to talk about or promise anything before I'd written it--and also because this has been my first time doing anything like this and I didn't want to flub anything up along the way. How I might've done that, who knows? But, I got a bit too busy to really worry about superstitions as the deadlines rolled on.

But now, it's out! And you should buy it! Lookee, lookee: It's already got a 5-star review from someone I don't even know!

For the moment, I'm going to wrap up this post, finish my dinner, and go for a walk with the girl--but, when we get back, I think I might post a few more details on what you'll find in my book debut.

Archived Comments

jose
2005-09-14T01:03:36

congrats, les, if anyone should have written that book it's you. i'm glad to see it's hit the shelves .. now to go find a copy and look it over :)
Jim Renaud
2005-09-14T01:54:39

Congrats Les. I am gonna need you to autograph mine!!! New site design, new box, new CMS... The world is your oyster!!! It's Les' world, we just live in it!!!
Matt Blackcustard
2005-09-14T02:52:08

Hell yeah!
Nick
2005-09-14T04:15:22

Just ordered mine...whens the book signing?.. Congrats man..
nf0
2005-09-19T21:41:49

I got my copy over the weekend. Some really good work!
l.m.orchard
2005-09-19T22:50:23

nf0: Hooray! Thanks for the kudos :)