Making AOSA: Tools

The Architecture of Open Source Applications books were multi-month projects involving dozens of people. It took a battery of different tools and processes to keep it all in line. This is the Academy Awards “thank you” speech post, where I acknowledge all the software that made this possible.

Managing the People

The heart of the whole operation was a Google Docs spreadsheet accessed by Greg and I. We had an “Authors/Editors” sheet which listed each author, their email address, chapter name, and Subversion ID and password. A separate sheet listed all the reviewers with their email, the two chapters they reviewed, and their status (e.g., waiting for a chapter, review expected in n days, etc.)

Thunderbird was invaluable for figuring out where each author was in the process. If you’re not familiar with Thunderbird, its storage concept is that you  tip every email you want to keep into an amorphous “archive” — no need to tag anything or save it to a particular folder. Then when you need that email again, you use Thunderbird’s search function to search for an email address or text string within the subject or body of the email.

I was able to search the email address of the author I was interested in, click “date” to sort the results by date, and immediately see the last conversation I had with that author. So if I searched for “Jane Doe” (say) and the latest email was from her saying, three weeks ago, “I should have my chapter ready in two weeks”, I knew it was time for a gentle nag.

Thunderbird mail client showing search results

Managing the Project

We used Subversion for version control. Lots of people have lots of opinions about Subversion, but I hadn’t used a version control system since CVS in university, and it seemed pretty okay to me. Each author had an account, but lots of people chose to submit their chapters by email instead. That worked fine, since there wasn’t a whole lot of back-and-forthing with edits.

I used a little app called TaskPaper to manage a few processes within the project. TaskPaper is a very simple app for creating and using checklists. For example, when we added a new contributor there was a long list of things to do: send them a welcome message, add them to Subversion, add empty placeholder files for their chapter to the repository, add them to the author list on the website… I was worried I would miss something, until I created a TaskPaper list.

Taskpaper showing list of actions for new contributor

Things also helped keep the train on the tracks. Things is a productivity app designed to implement the Getting Things Done system and I couldn’t do anything without it. Well, I suppose I could but I would exhaust the world’s supply of sticky notes.

Things list of AOSA actions

Notational Velocity is another part of my daily keeping-it-together arsenal. It’s a note-taking app which works with the Simplenote database. I used it to store information about the books (the required dimensions of the cover, the ISBNs), email snippets like the email I sent to reviewers or new contributors, and the solutions to different problems I had.

Notational Velocity showing notes pertaining to AOSA

Finally, the Google Docs spreadsheet had a very important role to play in managing the process. I created a “Chapter Status” sheet with one line per chapter, and used it to track where each chapter was in the process: first draft, first review, second draft, second review, copyediting, formatting, etc. Because I’m very visual and a colour junkie, I coded each status with a colour so I could look at the spreadsheet and immediately “feel” how we were doing.

Google spreadsheet showing progress of chapters

I also used vi for all the editing, Acorn for image editing (including creating the covers), and, reluctantly, Adobe Acrobat Pro to munge the final PDF so Lulu’s printers could reliably deal with it.

Thank you all! I couldn’t have done it without you!

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.