Subversive Collaboration

Last time I co-wrote a book, Gina Smith and I holed up in a hotel room for a week, laptop to laptop, banging out the text. I know what you're thinking, but the only steam was coming off the keyboards. There just wasn't a better way to collaborate on a book.

Fast forward 11 years and things are a lot different. Web 2.0 sites like 37Signals Backpack and Writeboard are designed for large, dispersed groups working on the same project. Wikis make it easy for groups to share information and collaborate on documents. I'm familiar with these solutions - we've been using a wiki to produce Call for Help for the past two years - but none of these are just right for writing.

Adam Engst of TidBits and Jason Snell of MacWorld Magazine obviously recognize the problem. They've issued a joint RFP for a collaborative editor worthy of the Mac. The article's worth reading for a list of programs they've tried and abandoned, but I think I might already have the solution.

I'm interested in the problem because I've decided to collaborate on another book. Amber MacArthur and I are working on a podcasting how-to. We want to write the definitive volume on creating your own audio or video show, covering everything from content, to production, to distribution, to making money. Between us we've learned quite a bit about the process - often inventing solutions to problems as they came up. Inspired by 37Signals's success with Getting Real, we plan to self-publish as a PDF, possibly with a printed book or CD-ROM version from Lulu. But before we sell it, we have to write it.

Amber's in Toronto. I'm in California. How can we work together without spending a week in a hotel room? And what about other authors we want to bring on for specific chapters? How do we incorporate their contributions?

Open source programmers accomplish the task very efficiently with version control systems like CVS and Subversion. Why can't we? (OK it might not be as much fun as holing up together at the Drake, but it's a lot less likely to cause problems with our respective significant others).

I've set up a Subversion server on one of my less used systems. It took about 10 minutes using a Red Hat RPM and the daemon version of the svn server. I've never used Subversion, or any version control system, but there's an excellent, free,  Subversion book that showed me what to do.

1. I created a temporary document folder on my local hard drive with sub-folders for the book's sections and individual text documents for the chapters (mkdir tmp/thebook, etc.)
   
2. created an empty repository on the server side (svnadmin create repository/thebook)
   
3. edited the repository's configuration files to make it private and added accounts and passwords for Amber and me (vi repository/thebook/conf/svnserve.conf)
   
4. uploaded the local copy to the server (svn import tmp/thebook svn://svnserver.com/thebook -m "initial import")
   
5. checked out the server's copy to my local hard drive and deleted the temp doc folder (svn checkout svn://svnserver.com/thebook)

From now on my work flow is to:

1. open Terminal and update my local copy with any changes from Amber (svn update ~/thebook)
2. write a bunch of stuff
3. open Terminal and save my changes back to the server (svn commit ~/thebook -m "notes for the log")
   

That's if I want to do take the trouble to open a terminal window - but as you'll see, I've found a text editor that eliminates even those simple steps.

Subversion can handle binary files, including Word documents, but I think we'll probably use a plain text editor since books don't typically use Word style formatting. (Publishers use codes much like the old Wordstar dot commands to indicate formatting.) There's a binary distribution of Subversion for OS X. I installed that on one machine. I used Fink to install svn on another Mac. And used Ubuntu's application installer to put it on my Linux box. There's a Windows client, too, although I haven't tried it. I've been able to easily checkout the document tree on all three machines, update it on each, then commit the changes back to the svn repository on the server.

It works flawlessly with one exception. I have had some problems with Mac files that have data and resource forks. svn doesn't see the resource fork so it munges the file. For example, I created a pair of Applescripts to automate the update and commit commands, but they didn't upload properly. The solution was to zip them first, but that's a gotcha for Mac users.

I've written up some simple instructions for Amber. It might confuse a less technically-proficient co-author, but she's very adept with these kind of things. She's going to install it tonight. I have high hopes. Subversion will allow us both to work on files locally (that's why I rejected Backpack - I didn't want to work only online), but makes it easy to update the server, and is great for backups because Subversion keeps all previous versions of all documents. If we happen to make conflicting changes to the same document, Subversion has good tools for merging the changes and figuring out what to keep.

The final piece of the puzzle is Textmate for the Macintosh. Textmate has built in support for Subversion. I can load the entire document tree as a Textmate project, easily add or move files, add text, and so on just by hitting Control-Shift-A in this very capable editor. This setup fits my ADD style of writing: A little here, a little there, iterating over the entire text as I think of things.

Textmate and Subversion are tools designed for programming teams, but there's not much difference between those teams and book authors. I'm thinking this will be a truly useful way to collaborate, and since we want to write the book in record time, it may be the only way to get it done.

I'd love to hear how other people are solving these issues, and suggestions you might have for making this setup better. We'll let you know how it works as the book progresses.