zerosum dirt(nap)

The single hardest thing about writing a book, I’ve decided, isn’t the writing part. It certainly isn’t the technical part either. I don’t mean to downplay my own skills or those of any other technical author, but the truth is that you don’t have to be a guru to write a fantastic book (it does help, of course).

The key to writing good book material is being able to show people how to do things while keeping them entertained. That means coming up with examples that tread the line between being practical, being appropriately demonstrative, and being correct. Good examples are the hard part.

When developing an example, you’re trying to come up with something that has the following characteristics:

• It’s interesting. That is, it’s worth writing about in the first place. No one wants to read another blog post creation example (unless there’s something unusual about it). BORING.
• It represents best practices. You’re an author. You have to be right. Or at least able to competently defend your implementation choices, anyway.
• It illustrates those concepts that you’re trying to write about. This should be first point, rather than third. See what I mean?
• It minimizes focus on those elements that you are not writing about. That is to say, we shouldn’t spend a lot of time talking about fuzzy bears, even though there are many different types of fuzzy bears, six species of which are listed as vulnerable or endangered by the World Conservation Union (whose headquarters are in the scenic Lake Geneva area of Gland, Switzerland).

The last point is a tricky one, but it’s important. You have to cut corners when creating good examples—but not the important ones or the ones that would prevent it from representing best practices. If you’re trying to illustrate, for example, how to build a tag cloud, you don’t want to spend lots of time on the CSS for making it pretty. Leave that to the CSS books.

If your example involves video transcoding, and the point is to illustrate the use of a message queue, you’re going to be really tempted to spend an extra 2-3 pages on certain format discrepancies or operational edge cases but DON’T. It’s interesting, sure, but if it’s not central to what you’re currently trying to demonstrate (message queues). You must resist.

If your example is a simple web service for sharing geographic location data and you’re using a bunch of RESTful conventions, make sure to explain the basic concepts. But don’t write a dissertation on REST vs SOAP. And don’t worry about responding to formats that aren’t part of the main example.

Just because it’s how you’d do it in a real-life project doesn’t mean it’s how you’d write about it or explain it to others. Keep it simple, lively, and (as Gold Five so succinctly put it before crashing his X-Wing) stay on target.

I've been bitten by the Twitter bug. I know, I'm a little late to the party. But being late is fashionable. And I sure like the fashion.

Anyway, go ahead and stalk me. If you dare. Or check out the status updates in the blog sidebar if that's what you're into. I've also added my DDJ blog feed to the sidebar. A couple of my recent articles:

• Roll Your Own Web Framework (an introduction to Rack)
• Rails: Vendor Everything Just Got Easier (the new config.gem features in Rails Edge)

More soon. Promise.

Like my pal bryanl over at smartic.us, I too want to apologize for being a bad blogger lately. I've just been stupid busy with both personal stuff and lotsa client work, which of course is both a blessing and a curse.

In any case, my head is almost back above water and I hope to be back on track writing regular (and hopefully interesting) posts within the next week or two. I've been working on some fun projects and I want to talk about it, really, but at the end of the day I'm just tired and don't know where to begin. I'll figure it out.

In the meantime, if you've got free cycles and some cash in your wallet to burn, pick up a copy of Dave Berube's new book on Ruby Reporting, which was just published by Apress. I served as a technical reviewer on it, which was a really great experience. Even though Dave and I don't see eye to eye on absolutely everything (cue groans about a particular chapter dealing with MS Access integration), it's full of fun Ruby code and unique reporting tips, including examples that interop with Google AdWords, SugarCRM, and PayPal. Congrats man, nice work!

So I updated this blog from Mephisto 0.7.3 to the latest trunk yesterday and I'm happy to report that the process was 100% painless. Edge has a number of nice nuggets missing from 0.7.x, which is over a year old at this point. In any case, thanks to Rick and the rest of the Mephisto team for the smooth upgrade path. I can't wait for 1.0, which I hear is rumored for a January release ;-).

While I was in the blog tweaking mood I also decided to install the mephisto_feedreader plugin and wired it up to display my shared items from Google Reader. This replaces the static "reading list" that was previously in the sidebar. I scan / read a good number of blogs, probably too many, and I often tag 2-3 things a day on average that I feel are useful / interesting / irreverent. Sharing is good and I have nothing to hide. For great justice!

So I finally got around to migrating the blog site over to Mephisto. I've only been planning on doing that for like 9 months. Horray for progress!

I'm probably a bit behind the game on this one, but huge props are due to Akismet for making my blog life just a bit more pleasant. Before it was installed last week, I was deleting hoards of comment spam every day. Today, none.

In other blog-related news, I'm still planning on moving productions over to Mephisto, but have been hard pressed for time lately. Fortunately (when I get around to it), it has Akismet support baked right in.

UPDATE: finally moved over to a new blogging platform! About time, eh?

Drupal has served me pretty well for a number of projects in the past. But as we shift our development focus towards Ruby-based projects, it seems like an ideal time to consider migrating my own blogging platform to something Rails-driven. Nothing against Drupal itself of course. Hell, for a PHP project it's pretty slick.

But it still just leaves me feeling like I'm flirting with an old (and somewhat unattractive) ex-girlfriend. It's not you, it's me.

The obvious candidates seem to be Typo and Mephisto. Another option would be to, of course, roll my own. But does the world really need another half-baked blogging engine? Probably not. If anyone has other recommendations let me know. Looks like I'm leaning towards Mephisto at this point.

Thus began the Zerosum dev blog, a place for folks who work on our code to muse about daily development happenings and such.

I’ve never been one to keep a blog, personally, but I think of this area as a useful place for us to post about things that don’t belong in our project trac wiki or elsewhere. Things you want to share with others. Things like: “Wow cool, Ian found a new way to do X that totally rocks. Spread the word” and “Rails migrations rule, check out this snippet!”, and “Saw this thing on Foo’s blog about how to do Y without needing Z. Maybe we should think about refactoring the BlahController to do that too?”

You get the idea.