How to Write a Hack for O’Reilly

[Ed note: this was originally posted on the O’Reilly Network on August 30, 2005.]

As lead editor for O’Reilly’s Hacks series, I field proposals for Hacks books on a daily basis. I also usually have several books in various stages of acquisition, writing, or production, all of which of course have authors and (this being Hacks) numerous contributors. Beyond the questions about which topical areas we’re looking to publish on, the questions that come up most often are usually variations on the theme of what makes a hack and how one should be written.

I’ve long wanted to write something for current and prospective authors, contributors, and other O’Reilly editors (to share with their authors) that explains exactly what we mean by “a nonobvious solution to an interesting problem.” But, of course, I haven’t had the time to do so, so I often go through various rounds of trying to explain something that, when it comes right down to it, you really need to just grok. Unfortunately, after a few attempts to put a fine point on the term hack (as used by O’Reilly), I often end up resorting to a description that’s not much better than Justice Stewart’s infamous definition of obscenity: namely, “I know it when I see it.”

Today, I was discussing a new project with Paul Bausch, who has established himself as a model author for the series (including Amazon Hacks, the forthcoming Yahoo! Hacks, an as-yet-unannounced third Hacks title, Flickr Hacks, and Google Hacks, Third Edition), and I learned that he’d quietly drafted his own take on this theme. Paul’s an author who groks the Hacks format with little need for supervision or guidance, so I was particularly interested in his perspective. He didn’t disappoint, so I asked him to share his sage advice with the world. Thankfully, he agreed.Here’s what he describes as his Hack template:

I view a hack as a project the reader can accomplish. The reader also needs to know why they might want to accomplish the project and have an idea of what the project should look like when they’re finished. Here’s my template:

1. Why this hack is needed (story, build desire)
2. Describe the relevant features
3. Hack prerequisites
4. Hack code/procedure
5. Example of the Hack in action
6. Brief summary (why the reader rocks!)

7. If possible, Hack alternatives

Whenever possible I use the conventional Hack headings of The Code and Running the Code to separate parts 4 and 5. And the heading Hacking the Hack for part 7.

The rest of his post fleshes out his philosophy and approach in more detail. Though there are certainly things I’d add if given the time, and other views and approaches are certainly welcome (Hacks contains multitudes: it always has room for a variety of perspectives and embraces diversity of opinions and approaches), Paul’s explanation and tips are as great a start as I could have hoped for.

If you’re thinking of writing for the Hacks series, currently writing for us, or just want to get a behind-the-scenes look at how the sausage is made, you’ll definitely not want to miss it.