onfocus

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. 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. 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. 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. 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. 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. 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. 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. 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.