Nimble Code: Category Books

A Year In Consumption

2006-12-30T10:43:32-08:00

This year, as an experiment I started living in public. By this, I don’t mean I jumped into the online exhibitionist extreme that seems to be required for MySpace users, but I have started tracking my media consumption of books/movies/music online. So, as a short post to tide everyone over until I gird myself to continue the never-ending newspapers series, here’s a review of my year in media.

In the last year, I read approximately 63 books, of which the most notable were:

The Ghost Map, by Steven Johnson
The Echo Maker, by Richard Powers
La Perdida, by Jessica Abel
Maps of the Imagination, by Peter Turchi
Rip It Up And Start Again, by Simon Reynolds

This last year I also saw approximately 67 movies and TV shows (new and rentals), of which the following 5 were the best, in no ranked order:

The New World
Little Miss Sunshine
Aguirre, The Wrath of God
Grizzly Man
Veronica Mars, seasons 1&2

Finally, here were the top 10 bands I listened to last year, courtesy of last.fm

Boards of Canada
Xela
Sigur Rós
Yeah Yeah Yeahs
Ms. John Soda
Thom Yorke
The American Analog Set
Ulrich Schnauss
Aphex Twin
Ladytron

Anyhow, there you have it; my life as a consumer for one year (but am I going to go see movies this weekend? Yes!) Anyhow, happy new year and see you all next year! If you’ll excuse me, I’ve got some more books to read.

Rubyisms In Rails DRM Woes?

2006-08-25T16:02:00-07:00

Sorry for the silence. I was on vacation in Alaska recently, so I’ve not really been in the blogging mood. But here is a short note and plea for understanding.

Early reviews (okay, review as I’ve only had one; let me know if you’ve written one or want to do a review) of the ebook have been encouragingly favorable, but the biggest complaints I’ve gotten so far have been about the DRM. I have spoken to my publisher and she’s informed me this was a mistake that was corrected after the first day, and if you’ve been stung with a DRM-afflicted version, we will provide you with a DRM-free replacement. Furthermore, no books in the Ruby Shortcut series will have DRM.

The best way to do this would be to mail me directly and I will pass along your email address to my publisher to send you a replacement copy. My email address is harrisj @ schizopolis.net. It’s probably easier to just click that mailto link above though.

Sorry for the problems. This is a new direction for them and me, and I guess we still had a few kinks to work out. Thanks for your patience.

Rubyisms in Rails Redux

2006-08-02T09:46:00-07:00

self.promote!

I am pleased to announce that the digital shortcut PDF version (to purchase, you have to go to the Digital Shortcuts page or you can buy it from Safari Sorry!) of my Rubyisms in Rails presentation is finally available for purchase. At 54 pages in length for the low price of $9.99, I guarantee you’ll glean at least 18.5 cents of insight from each page (disclaimer: that’s a mean instructional value; although gorgeous, the title page is not particularly educational in itself).

In addition, the book is also now available in Safari Books Online, and possibly Amazon or other retailers as well. Also, be sure to check out the list of other upcoming Ruby titles.

So, what’s in it? If you’ve read the original presentation, you already have a sense of the scope of material I am covering here, but the shortcut allows me to focus on the material in greater depth. The result is a richer and more thorough examination of the examples presented in the original slides. If you are an intermediate to advanced Rails hacker, you probably know all this stuff already. But if you are a newcomer to Ruby through Rails, or you still find yourself still stuck coding PHP or Java-like Ruby, this ebook might help to align your thinking to the Ruby way.

Will I write another ebook? I’d say yes, but I’ll have to think up another interesting topic. But if you are ever thinking of creating a technical book, I’d recommend starting in a smaller dose like this first. As I discovered, even 54 pages can be a lot of work, and it’s better to test out your time commitments and abilities with something small before you start pitching large references. But that’s a topic for another blog posting. Make me happy: Buy the ebook or read it on Safari and give me your feedback. Thanks!

Update

Fixed purchase link to be go to Shortcuts page (where you can add to cart).

Quality Ingredients: Story, Voice, and Metaphor

2006-06-20T17:02:00-07:00

I’ve been thinking a lot about writing lately. There’s been a practical reason — I’ve written an ebook version of Rubyisms on Rails that I’ll tell you more about later — but my motivations are more abstract. I’ve been reading way too many technical books lately. Many have been good, but as one afternoon browsing the bookshelves will demonstrate, most are terrible. As Joel Spolsky exclaims in exasperation in the forward to the excellent book of software essays The Best Software Writing 1:

The software development world desperately needs better writing. If I have to read another 200-page book about some class library written by 16 separate people in broken ESL, I’m going to flip out. If I see another hardback book about object-oriented models written with dense faux-academic pretentiousness, I’m not going to shelve it any more in the Fog Creek library: it’s going right in the recycle bin. If I have to read another spirited attack on Microsoft’s buggy code by an enthusiastic nine-year-old Trekkie on Slashdot, I might just poke my eyes out with a sharpened pencil. Stop it, stop it, stop it!

For Spolsky, the most important ingredient missing from dull technical books is story. As he puts it, good tech writing captures your interest by creating a plausible or interesting story. The resulting text may be much more verbose — in an example, he spins out the insipid truism “a good team leader provides inspiration by setting a good example” into an involved 400 word story — but the story is what makes you want to keep reading more. Looking at some recent purchases, I can see the effectiveness in some notable recent books. In the simplest case, you can go far with a compelling example application you elaborate in each successive chapter like Enterprise Integration with Ruby does. is built on the solid story of an example integrated in each chapter. It’s not necessary to have one big story, however. You can also structure your book as a sequence of independent smaller stories, as recent favorites Practices of an Agile Developer and The Art of Project Management did so well.

On a contrasting note, Amy Hoy in an article disparaging the suggestion that being a woman is what solely makes her a good writer, suggests another important ingredient is ~~breasts~~ voice. The way to make a technical article compelling is to make it personable. This is something that Joel hints at with his dig at “16 separate writers” and it is something certainly borne out by the selections in the book — practically every selection is a blog posting and is thus opionated, direct, and personal by their very nature — but Joel focuses more on what is being said than how it is said. Voice matters, and nobody has done as good a job asserting the importance of a personal tone than Amy has. But it’s hard for technical writers to understand. When we are first learning to write essays in elementary school, we’re taught to prize dispassionate objectivity above a personal voice. This is not to blame teachers; that makes a lot of sense when you’re teaching writing to fifth graders whose idea of an argument might run along the lines of “This book is bad because I didn’t like it,” and good writers learn eventually to balance their personal opinions and objective fact in essays. Unfortunately, nerds usually aren’t good writers, and I think too many books are written by developers too mortified to express their personalities (even if they could). But if you edit out your personality from your writing, you might as well do your readers a favor and delete the whole book. An example of books that benefit from voice are Martin Fowler’s classic Refactoring and the more recent book Refactoring Databases. Refactoring code is a discussion prone to tedium, but the books succeed because they sparkle with clarity and reflect the single voices of their authors.

Before I continue, I should clarify a few points. Joel’s emphasis on story and Amy’s on voice are not mutually exclusive: I can explicitly emphasize that something happened to me or something happened to me, but both voice and story exist in any compelling technical narrative. The second point is you can only do so much. There will be always be some dullness that’s unavoidable in technical literature. It’s simply impossible to make some content interesting (ever read a truly fun man page ever?), and if you tried to make it fun, you’ll actually annoy your readers (“Hey kids! Let’s sing the arguments to GCC as a song!”). But a technical book is more than a listing of compiler options or valid function parameter or working code samples. Like introns in DNA, the bulk of any technical work is interstitial material that holds the boring stuff together. And that is where your writing should shine.

Which brings me to my point. I want to draw attention to another important ingredient that complements those two yet gets short shrift: metaphor. To see what I mean by metaphor in action, look at my DNA example from the previous paragraph (I know, technically it’s a simile). Assuming you knew what an intron is — in a book I obviously would explain it more explicitly than a blog post — that aside conjures up a rich web of allusion that clarifies the emphasis of the point (that the bulk of your book might not be technically explicit and yet still be meaningful for the whole). The beauty of metaphors is they evoke all sorts of mental associations in your readers that act like scaffolding (a metaphor) that helps your readers learn material by building upon concepts they’re innately familiar with. And they come with an expressive power that allow you to express complicated ideas succinctly through allusion (ie, instead of having to spell out what scaffolding is used for like I just did, you can just describe it as scaffolding and leave the reader’s brain to fill in the rest).

Metaphors are truly useful things, and since this is my soapbox (another metaphor!), I’ll declare that metaphors are woefully under-utilized in technical writing. I think one reason for this is technical writers are discouraged from metaphor to be more universal — if I make a metaphor specific to New York City, it might fall flat to a reader in Germany or India; not only would I have to explain my technical content, I’d have to explain my metaphor! You can avoid regionalism pretty easily though, so I think the biggest stumbling block is geeks themselves. Mainly, that same literal geek writer that sticks to the facts and recoils in horror from anything that smacks of poetry.

This is a dearth made more unfortunate because good metaphors reinforce both story and voice. If you are boring like me and have no personal experiences to relate, you can fabricate your narrative on the back of a metaphor instead. And your use of metaphor breaks your text out of the dry and technical and provides a place for your unique personal voice to be expressed. To give an example of this in action, I recently had to explain the virtue of iterators in Ruby for the ebook on Rubyisms. I could describe how they work technically easy enough, but I felt that a metaphor was the best way to explain why iterators make more sense (and given the number of programmers still iterating through array elements in Java, this is something most programmers still don’t understand). So I brought out an unlikely metaphor to anchor why iterators are better: traveling crosscountry on local roads vs. highways.

I’ve described this book as a drive down local roads, but now it’s time to take to the highways. Highways are fascinating concepts. Although they seem like an inevitable part of the driving infrastructure, highways are actually quite new in the history of roads. As recently as the early 1900s for instance, a drive across the country was essentially the same as driving across town, navigating a dense network of local roads that would get you there eventually but not efficiently. Routes were not clearly demarcated, and road maps as we know them didn’t exist. Each driver would have to figure out their own routes, a challenge when navigation comprised only instructions like “take right at third fork in the road” or “turn left at the willow tree.” Of course, getting lost was inevitable. And accidents and mishaps were all too common on neglected backcountry roads. This might seem a cartoonish depiction of long-distance driving, but it’s that’s largely a reflection on just how fast, safe, predictable, and even boring intercity travel has become due to highways. And that’s because the highway changed the very nature of long-distance trips.

Highways are built not from asphalt and cement, but from limitations. Instead of connecting to every road, a highway runs largely isolated from local roads with only a scant selection of exits where new traffic can enter and leave. Highways never actually intersect directly with other roads except by exits and ramps, meaning traffic control mechanisms like rotaries and stop lights aren’t needed and traffic can move faster. This also has the additional effect of discouraging local traffic from taking the road, leaving the road for the serious long-haul motorists. Most significantly of all, highways simplify navigation. Rather than picking a route over local roads, the highway is a road that limits your route. To enter a highways is to largely surrender navigational choices: there are no turns or forks in the road to decide among; backtracking and U-turns are forbidden; your only option is to drive forward until you reach your exit. You can drive faster because you have less to decide, and you can navigate easier because you have less to consider. And so a trip from New York to Chicago used to be an impossible slog of endless directions. Now, it’s a largely mundane trip of only 3 highway segments (although admittedly, you stay on I-80 for an astonishing 750 miles of the way).

I then go on to explain that running through array elements by incrementing an integer index is a lot like driving cross country on local roads, prone to complexity, mishap and error. From there, an Iterator is a lot like a highway, less worrying about navigation, more involvement with the act of driving. I’m not posting this example to toot my horn in any way (and not as a teaser for the book, although it works that way). It’s just a nice recent case where I pulled a metaphor out of my writer’s toolbox. From there, I was able to spin out the explicit technical reasons why it’s better to use iterators, but I feel I can succeed because the reader is able to relate to the scaffolding of highway driving, a metaphor well understood by much of my audience (sorry to readers in deepest Papua-New Guinea). I think you’ll agree it’s a lot more vivid to think of access violations as wrong turns and fencepost errors as navigational errors. You can’t help but learn the material because you already know it in some sense. Metaphors aren’t poetic navel-gazing, they’re a necessary ingredient to the book. So, mix them in sometime. I think you’ll like the taste.

Update: The book is coming out soon. I’ll post details when I know. Watch for an announcement soon. I promise!

Three Novels For Programmers

2006-05-12T16:28:00-07:00

A couple weekends ago, I went on a trip up to the People’s Republic of Cambridge, Massachusetts. While my wife was at a conference, I spent my time writing, thinking, and catching up with a few old friends from MIT about all the things that have been going on while I’ve been here in New York: changes to campus life, hideous new architecture, notable hacks, and the fact that my beloved dorm of Senior House still seems to be the same merry land of malcontents and eccentrics. We talked about many other things, but I recall most clearly the talk about books.

The common stereotype of computer nerds is that we spend all of our non-technical reading time with noses deep in cheap mass-market science fiction paperbacks featuring lizard men, busty women, and spaceships pointing phallicly towards a planet. But this seems more of a cheap joke than a deep truth; the geeks I know love novels. And so, in an attempt to convince the world that computer people have a special depth, I’m starting my own version of a book meme and naming three notable books along a theme and why I like them. I know this is of course what is known as filler in blog land, but it might be fun anyway. So, first up in my listing is three excellent novels for computer scientists that aren’t science fiction:

Galatea 2.2 by Richard Powers is a wistful and intriguing book about a writer named “Richard Powers” who returns from a failed life in Holland for a directionless sabbatical at a Midwestern university. While there, he becomes involved with a project in the university’s large Computer Science department to teach an Artificial Intelligence named Helen about art, literature and beauty. The result is an exploration of identity, consciousness and the emotional connections we feel with machines, made the more interesting by the intermingling of the author’s real and fictional personas in the book.

Mefisto by John Banville is a hypnotic retelling of the Faust story from Ireland’s best contemporary writer. The book comprise two symmetric episodes of the life of a main character gifted in mathematics who falls into the orbit of a seductively mysterious man. Equivalences, symbols and symmetry (it’s no coincidence the book begins and ends with the word “chance”) make for some interesting connections without the gimmicky annoyances of more experimental textual structure. Those of the scientific bent may also prefer Banville’s books Kepler and Copernicus.

Gravity’s Rainbow by Thomas Pynchon is a mess of a book. Ostensibly dealing with a mystery about the V-2 rockets at the end of World War II, it becomes a grand descent into some disparate subjects as chemicals, sado-masochism, conditioning, identity, race, and an immortal lightbulb. It might not make complete sense the first time through (or even subsequent times), but it definitely is a dense exercise in style unmatched by any. Besides, any novel that can inspire cool art like this can’t be bad.

What’s the next Three? I don’t know. Maybe poetry for pretentious people or weird books that mix text and pictures. Feel free to do your own or make a suggestion below.

My Job Went To India

2005-09-30T01:55:00-07:00

A pleasant surprise was waiting for me when I got home today. A copy of Chad Fowler’s excellent book My Job Went To India was waiting for me in the mail. I’m not sure that I can give an objective review (for reasons I’ll go into here), but if you are serious about making a career in programming, you should buy this book.

What Mr. Fowler does here is to take a fair and interesting look at how outsourcing has affected the field of software development. If you want a breathy ode to a flat world where we’re all information works or a hysterical screed against them foreigners taking jobs, this is not a book for you. But if you’re a programmer like me who likes to develop, but also wants to know how to control his career, this book has the pragmatic information you need.

The problem is, most software devlopers really don’t deserve their jobs more than a given developer in India or somewhere else (don’t fault them for their zeal and definitely do not underestimate their smarts). We usually fail in several ways:

Skills. Have you learned any new technologies in the last year? How much do you control how you design and implement things, or do you just mindlessly code specs given from on high?
Business. Any developer can see the technical dimensions of a problem, but very few are able to grasp the business side of their jobs. Do you know your business domain? Do you understand how the bottom line at your company works?
Communication. The stereotype of the developer as a lone wolf working strange hours and sitting sullenly in a dark office is often all too true. This needs to change. If the CEO of your company doesn’t understand what you do, why exactly would he think it couldn’t be done better in India?
Marketing. There is a world outside of your company. Should you lose your job, what sort of network do you have to draw on? And what exactly would convince an employer to hire you?
Passion. Finally, are you sure you even want to be a developer in the first place? Is this a career you fell into, or one you want to fight for?

As I was noting earlier, self promotion is one of biggest failings of geeks these days. I realized this was my biggest problem last year, but I’m glad to see such an authoritative and well-crafted examination of the problem in Chad’s book.

Which brings me to why I must concede I can’t give an entirely objective review to this book. Around six months ago, I decided to get more involved in the online community. I started blogging, and I started reading blogs of alpha geeks whose judgements I respected. This included people in the Ruby on Rails community, and Chad’s blog was one of them. A short time later, Chad asked for test readers for his draft manuscript, and I offered to help. He accepted me as a test editor, and i enjoyed the experience immensely. It was a great way to test the strength of his book and correct weaknesses, and I have to commend Chad for it. And I’m proud I could help out and become more involved with my career in the process. It’s a good book. Buy it. It’s worth it.