In August 2012 Joy Beatty, vice-president of research and development at Seilevel, asked me if I had thought about writing a third edition of my popular book Software Requirements. The first edition was published in 1999 and the second in 2003, both by Microsoft Press. I had indeed thought about writing a third edition from time to time. While virtually everything I described in the second edition is still valid and useful 10 years later, the book would benefit from an update in many respects. Some important changes have taken place in the software business and the world of business analysis in the intervening years. Frankly, though, the prospect of revising a 500-page book was daunting. I knew it would be a massive amount of work. I hadn’t been following the software requirements literature closely since I largely retired from consulting and training a few years ago. The hammock, my guitars, and my volunteer work were more appealing than spending hundreds of hours at a keyboard.
Nevertheless, Joy’s question got me to thinking. What if she and I were to co-author the third edition of the book? Joy is well respected in the business analysis field, very much up on current happenings in the domain, and the co-author herself of a nice book called Visual Models for Software Requirements that was published by Microsoft Press in 2012. So we began kicking this possibility around. Before long it became clear that there might be value in this collaboration. We agreed to give it a try.
Requirements for RequirementsOur first task was to create an outline. We began with the outline for the second edition (what the publishers call a 2E). We identified chapters that would benefit from major enhancements, chapters that just needed a tune-up and refresh, and new topics that we could add. We each went through a copy of the 2E and made notes about specific changes to make. I came up with more than 150 sticky notes with ideas, strategically placed at the relevant sections in the 2E. My email archives contained more than 60 email exchanges I had had with readers over the years (including several with Joy from 2004 and 2008!) addressing questions they had raised. Those were a useful source of other improvement ideas and stories to share.
Joy and I settled fairly quickly on the overall chapter structure and our preliminary first- and second-level headings. Then we enhanced this outline, each of us adding bullets under each chapter with our thoughts about possible changes to make. This annotated outline—which we call the AO—has been our primary working medium for exchanging thoughts and ideas. In essence, that outline and all the associated notes established the requirements for our book on requirements.
The high-level outline also was incorporated into the proposal that we submitted to Microsoft Press. Joy and I were very pleased when Microsoft accepted our proposal, as they’ve done a very nice job for us on our previous books.
Across the MilesI live in Portland, Oregon. Joy lives in Austin, Texas. We have only met once in person, a couple of years ago at a conference, although we have had other professional interactions over the years. We needed to figure out the most efficient and reliable way to exchange materials throughout the duration of this many-month project.
Joy established a Microsoft SharePoint repository for us to use as a configuration management tool. We also set up an issues list to keep track of some of the myriad questions that arise. We created the following folders in the repository for managing our files:
- The final chapter files from the 2E, which served as a great starting point for much of the new book.
- The drafted chapters that we would be iterating on during creation, when making our own revisions, and during peer review.
- An infrastructure folder to store various working documents: status tracking spreadsheet, chapter checklist, collaboration process, reviewer’s guide for our peer reviewers, and so forth.
- A folder for the many figures and other images to appear in the book, organized by chapter.
- A folder for the submitted chapters that went off to the publisher for copy editing and the revised versions the publisher sent back to us.
- A folder for PDFs of the final chapters that we receive from the publisher for proofreading.
Planning the CollaborationI have long suspected that many teams of people who work together on a project don’t spend much time thinking about how they’re going to work together. They can do fine for a while, but when deadlines loom, there is too much going on, and the stress level ramps up, the lack of a process begins to show. So Joy and I spent quite a bit of time working through the process we would follow for collaboration on the different aspects of this book.
Each us took responsibility for being the primary author on certain chapters; we’ve adjusted that allocation as we went along to share the workload equitably. We crafted a detailed process to describe how we would hand materials off from one to the other, process feedback received from our reviewers, and handle the interactions with the publisher’s editorial team. We also agreed on some writing style and format issues. One goal was to give the book a consistent feel and style such that it would not be apparent to a reader which of us had written each chapter. This was perhaps easier on those chapters for which we began with the version published in the second edition of the book. But even on new chapters, the numerous passes we made back and forth smoothed out the final presentation. It was well worth the time we spent working out this collaboration process.
In part 2 of this article I'll describe how we carefully tracked the status of the many elements that make up the full book (it wasn't simple!) and summarize my observations about this collaboration experience.
(If you found this article helpful, please consider making a donation to the Norm Kerth Benefit Fund to help a consultant who has been disabled since 1999 with a traumatic brain injury from a car accident. You can read Norm's story or donate here. Thanks!)