Hello! Karl Wiegers here. I’m doing something right know that I’ve never done before: co-authoring a book. It’s a new experience for me, but it’s going remarkably well. I’ve written several articles with co-authors over the years, which went fine, but nothing like the scale of the book. If you’ve ever thought about writing something with someone else, you might find the story of how we approached this to be interesting.
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 (Microsoft Press, 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 Requirements
Our 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 Miles
I 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.
As each of us uploads modified versions of a chapter or other document to one of these folders, it gets added to the collection so we retain the history of previous versions. We use check-out and check-in procedures to make sure that only one of us at a time can make changes in a particular file. This basic configuration management discipline has worked very well to keep us from overwriting each other’s work or losing changes one of us has made.
Planning the Collaboration
I 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.
When writing a book, there is a vast amount of information to keep track of. At any given time one of our chapters can be in one of many possible states:
- Not yet begun
- Initial draft written
- Initial draft being reviewed by the other author
- Reviewed draft being revised by primary author
- Out for peer review
- Being revised following peer review
- Being edited by our own internal editor
- Submitted to publisher for copy editing
- Being revised following copy editing
- Final manuscript version submitted to publisher
- Formatted PDF pages and artwork received from publisher
- Formatted PDF pages being proofread and corrected
- Final final final pages submitted to publisher
Our book contains a total of about 40 components—chapters, front matter, and back matter—plus more than 100 image files, and we are working on many of them simultaneously in these various states. Sometimes I feel as though I’m juggling 20 flaming chainsaws. We set up a spreadsheet to track the date each chapter transitioned from one of these statuses to another. Each of us had to maintain our own set of pending revisions to the shared tracking spreadsheet so we wouldn’t step on each other’s changes when we updated it periodically. We also had a tracking spreadsheet for review status. We recorded when each chapter went out for peer review, the target date for receiving review feedback, the actual date we received feedback from each reviewer, and a rating of how useful each reviewer’s input was.
Tracking status carefully like this was essential for us to make sure that we always knew what each of us should be working on. It helped ensure that could make our target dates for getting chapters where they needed to be at the right time. Speaking of which, we spent quite a bit of time scheduling those target dates for critical chapter milestones and rescheduling them as we saw how the work progressed. We had a lot of schedule flexibility until the publisher’s editorial team was put into place. At that point, they needed a firm schedule of when they could expect to see chapters, and they needed predictable turnaround on our review of copyedited chapters and final page proofs. When the editorial team was assembled, the project changed from being more or less open-ended to being timeboxed with firm constraints. I take pride in having never missed a deadline for any of the articles or books I’ve written, and I’m going to try hard to make sure I don’t break that record with this project.
Writing this book has been an interesting and fun experience. Joy has been, well, a joy to work with. She closes important gaps in my own knowledge, and she brings a broad set of experiences and stories to share. Fortunately, our underlying philosophies and perspectives are very similar. Those minor disagreements that we have are easily worked out through the dozens of emails we exchange each day and the occasional phone discussion. It’s been great to have someone to bounce ideas off, to clarify my thinking, to help me choose between different possible approaches, and to straighten me out when I’m off in the weeds. Joy has also obtained some input from time to time from her colleagues at Seilevel, running small chunks of text past them to test their reaction. This quick, real-world input saved us from ourselves more than once.
You might think that working with a co-author who has responsibility for many of the chapters would save time. That has not been my experience. If anything, this book is taking more time than if I were doing it all myself. That’s mainly because each chapter goes through more iterations than if only one author was involved. However, there are some important advantages. First, I couldn’t do it all myself. Joy has expertise that allows her to write chapters and sections that I simply could not. She has taken some of the chapters that I had written years ago for the second edition and greatly enhanced and updated them.
In addition, working with a co-author has made the material I’m writing much better. On my previous books, I just did the best job I could on a draft chapter and sent it out to a dozen or so reviewers. This time, Joy and I are spending a lot of time going over each other’s work before the reviewers ever see it. We commit acts of unspeakable editorial brutality on each other’s writing (politely, of course), all for a good cause. We are each other’s toughest critic. As a consequence, our ultimate presentation of each topic is much clearer and more thorough than it would have been otherwise. It has also been great to have somebody to kick ideas around with, to help me determine the best way to approach a particular topic or whether to cover it at all. We’ve learned a lot from each other, and the quality of the work shows the benefit.
All that said, I’ll still be glad when it’s done!