My Writing Workflow

Today marks the start of PragProWriMo, where the fine folks over at the Pragmatic Bookshelf{.popup} are encouraging aspiring writers to write a technical book over the course of the month. Over at the forums{.popup}, I shared my writing workflow, which I’m reposting here.

My process may not be a good fit for everyone, but it’s served me quite well.

I usually map out my idea using either OmniOutliner{.popup} or the free online CheckVist{.popup} app. I used to use mindmaps but I found them just a little too distracting. CheckVist can export OPML formats which you can bring into a mindmapping software or even convert to HTML or Docbook markup if you want.

Once I have my thoughts down I start narrowing down my focus a bit. I think about my audience and think specifically about someone I know who would benefit from this book. It might be the designer who needs just a little help with jQuery, or it might be the Java programmer with years of experience that wants to pick up Ruby. But I’m pretty specific, and I found that the best approach really is to target one specific type of reader, rather than to try to be all things to everyone. That said, you do need to make that abundantly clear to the prospective reader.

Once I’ve gotten a topic and a target audience, I start filling in the blanks in my outline with some good “introductory” text for each node in my outline. If I can’t think of an elevator pitch for each one, I either decide if I need to learn it, and mark it as research, or I evaluate if it’s really in scope for my reader and target audience. Sometimes things we want to teach aren’t what our readers need to know right now.

Andy Hunt’s _Pragmatic Thinking and Learning_is a great book, and it has a chapter that explores the Dreyfus Model of Skills Acquisition. This model has stages people progress through when learning anything new. I’ve found that the best books take people from one of these stages to the next. I try to do that with my writing.

So, now that I have my topic, target audience, and a good idea about what I’m writing, I start writing. I write about whatever interests me first, which means I may have three or four chapters going at a time. I try to write EVERY day. Even just for a little bit, because having to miss one day of writing due to a kid’s sports game is better than not writing all week, trying to cram it all in on Saturday, only to be hit with having to go to a kid’s sports game. If you do that, you’re now a week behind.

Once I’ve got a chapter completed, I export it to a PDF on my iPad to do some reviewing and editing. This is also where I PHYSICALLY CHANGE LOCATIONS. Using a different medium and a different location puts me in a separate mindset. It seems like a silly trick, but it works. B

When I’m writing books that have source code, I use a Git repository with a branch for each version. I’ll use 0001_start and 00025_refactoring or things like that so they’re sequential. I can then export each branch to a directory structure so I have code my readers can download. This also makes it easier if I discover that I left an important step out in earlier code – I can simply commit and rebase or cherry-pick it through to the later versions.

I tend to write my code at night and my prose during the day. And I tend to write code first and write the prose around it. I’m a better coder at night, it seems.

Once I have a few chapters, I start looking at introductions and conclusions. I usually don’t even try to write these until I have a few chapters because I don’t really see how things fit until that point.

I can average a 20 page chapter every two weeks, and sometimes faster. But you have to keep in mind that faster is better. For more perspective, a 10 chapter book would now take me 20 weeks, or close to six months! So it all comes back to making the time to make this happen, writing every day.

As for what I use for writing, I do everything in either Vim or TextMate, and I use DocBook, which is an XML markup. It’s something I picked up in 2006 and can’t live without, but it’s not for everyone. It’s more important to write good stuff than it is to fixate on tools or process. You’ll find those things will distract you too much if you let them.

So that’s my process. If you have questions, feel free to ask away.