Making AOSA: ToolsPosted: June 12, 2012
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.
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.
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.
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.
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.
Thank you all! I couldn’t have done it without you!