Shostack + Friends Blog Archive


Writing a book: technical tools & collaboration

When Andrew and I started writing The New School, we both lived in Atlanta, only a few miles apart. We regularly met for beer or coffee to review drafts. After I moved to Seattle, our working process changed a lot. I wanted to talk both about the tools we used, and our writing process.

We started with text editors and a subversion repository. Andrew, I think, used TextEdit, and I used emacs. This didn’t work very well, and we regularly lost check-in discipline. We also realized that we both wanted to be able to use headings, italics, and other tools that aren’t easy in text.

So we moved to LaTex. LaTex is a very powerful, slightly twitchy page description system that scientists use. We wrote the draft chapters we used to sell the book in LaTex, along with the proposal. We really like those drafts, and there’s a good deal which survived, and even more that’s gone. We marked up those chapters in person, which became a lot harder when I took a job in Seattle.

As we tried to work in LaTex, we ran into the same collaboration troubles that Baron Schwartz talked about in “What is it like to write a technical book?“* [link to no longer works] Lists of comments just didn’t cut it. We needed something more powerful.

Now, there’s a few publishers left who take three formats: LaTeX, Word, and camera-ready. (As I understand it, most only take Word.) So our choice of formats controlled our choice of software. My experience with OpenOffice is that it didn’t produce perfect Office docs. We didn’t want to take a risk that we’d be stuck in a format war with AW. So we moved to Office 2004 for the Mac, and it worked pretty well for writing and revising. Ironically, I was the one who resisted Word most strongly. I’m a real fan of simple file formats that you can read with various tools. We used iChat’s voice chat feature to talk through things, and Andrew flew up to Seattle once for a grueling-long weekend of editing.

That worked pretty well until we hit technical reviews and production. Technical reviews involved sending out the draft to a bunch of people, who then commented on it, usually using Word’s comment feature. I aggregated all those into one file, and started editing it. When we did, we ran into performance problems. A 20 page doc with 300-400 comments and edits was slow.

Fortunately, assimilation has its privileges. I was able to get us into the Office 2008 beta program, which ran almost flawlessly for us. We did the final production edits with Office 2008, ichat and one other key tool: my Brother HL5140 printer. It was a workhorse, and the huge stacks of paper that I worked with all came out of a single cartridge.

*I think that’s the right URL. He has some silly anti-spam software that can’t tell the difference between GET and POST and complains about not having a referer: header on GET.