How I Write a Hack

I was chatting with Brian Sawyer (Hacks Series editor) earlier today about writing Hacks and the process I use, and he encouraged me to share the way I work. I think it's a bit like making sausage, you don't necessarily want to know what an author uses to put something together. But hopefully sharing my process will help other tech writers, or may encourage others to share the way they work. So here's a quick look at how I write a Hack.

Everyone has their own methods and process for writing, and here are the methods I used for Yahoo! Hacks. I printed out and taped the following numbered lists to my monitor, and reading over them helped me come up with supporting material for each Hack.
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.
Hack Process
If the Hack is going to be centered on a piece of code, I like to write that first and get it working smoothly. Once the code is ready to go, parts 3, 4, and 5 are fairly easy to put together. If the Hack is more basic/explanatory, I'll often start at part 1.
Hack Motivations
Part 1 is always the hardest for me, so my other lists revolve around how to frame a Hack for a reader. I've found that William Zinsser's On Writing Well has been a big help to me, and some of these ideas are straight from the book.
Central Transaction
Zinsser talks about a central transaction for any piece of writing, and the one I came up with for Hacks is: Hacker's love affair with technology. I felt like I wanted to convey excitement about technology throughout the book, and I always kept this phrase in mind.
Telling a Story
I only wrote in first person using I once or twice in Yahoo! Hacks. I was more comfortable writing in third person. I still tried to keep the idea of telling a story in mind, and I found this list helpful:
  1. How was I drawn into the Hack?
  2. What emotional baggage did I bring?
  3. How has the Hack changed my life?
  4. Tell with humanity and warmth.
Of course not every Hack is a life-changing experience, but the Hack probably did affect me in some small way: made something more convenient, helped me see something in a different way, let me share something with my friends, etc.
Building Desire
I've found that it's not always easy to explain why someone should be interested in a particular Hack, but I think it's crucial. Here's the list of potential motivations that I tack up:
  1. aesthetic (appreciation of beauty or good taste)
  2. competitive (giving an advantage or keeping up)
  3. gregarious (enjoying the company of others)
  4. snobbish (regarding social inferiority)
  5. exhibitionist (attract attention, show-off)
  6. maternal (protect, warm and nurturing)
For Yahoo! Hacks I found that there are two basic varieties of Hack: Visualization and Productivity. Visualization Hacks let you see data in a new or unusual way and Productivity Hacks let you do something you already do more efficiently. So the motivations that I found most compatible were aesthetic for visualization hacks, and competitive for productivity hacks. Although gregarious and exhibitionist motivations worked well for community-oriented hacks. I don't use these exact words in the hack, but I might say something like, "this hack has a minimalist charm," that appeals to the aesthetic desire. Once I find how I'm going to frame the Hack by showing the reader why it's great, the words flow for me from there.
Hack Subjects
Part 2 of the template is important because it's a chance to describe the service in detail. I always assume that the reader only has a passing knowledge of whatever I'm writing about, so I like to describe the details of basic features of a service in part 2. For example, if I have a Hack that shows how to scrape a site for movie times and create a custom email with listings in their area, I first want to show someone how to get movie times the standard way through the website, along with any tips and tricks for using the site. Then I'll go into taking those features a step further with the Hack. I feel that without understanding a feature as it was intended to be used first, the Hack won't make as much sense.
Hack Summary
I'm not very good at this, but I try to add a sentence or two at the end of the Hack that taps into the motivation from the beginning of the Hack. I think it gives the Hack a sense of completeness.

That's it! Of course much of this process is tied to the conventions established in the excellent Hacks series, and I hope sharing this will encourage others to take a stab at writing for the series. You'll have to see if you can spot these methods in action when Yahoo! Hacks is out in a month or so.

Comments

Great summary, pb. I'm fascinated by the writing process, and how actual publish authors approach their work. I admire — and envy — your ability to make money at this. Good work!

I, too, like On Writing Well. What other writing books have you enjoyed and/or benefited from? I often find that although I've read and understood various manuals on good writing, putting the concepts into practice is more difficult. Do you have to force yourself to think about following various rules/guidelines for writing?
Thanks, JD! Yahoo! Hacks was only the 3rd book I've ever worked on, so I'm definitely still developing a process that works for me. You should take any of my writing advice with a grain of salt. ;)

I haven't found any books about writing to match Zinsser's. Though I've read quite a few books about public relations, marketing (groan!), and psychology that have helped. This sounds like a good topic for another post. :)

I think strict rules are very important for writing and that's why I turned the Hacks format into a template for myself. In fact, I wish there were more limitations about what a Hack is and what a Hack isn't--it would make my job easier. I'm always trying to find ways to put limitations on what's possible, or give myself a select menu of items to work with. (My creative writing class self from college would hate this paragraph.)

Again, in the scheme of things I'm a newbie writer so I'm not drawing on a wealth of experience here.
Thanks for Google Smackdown...it's WONDERFUL!!!