The book sprint

Not just for code anymore

OpenStack Operations GuideDo you really want a technical book for your project? Does your community need to provide more helpful docs to support even more users? Does your community have a lot of knowledge they need to get out of heads and into bits and bytes? Do you have a good mix of technical experts and technical writers and users who would enjoy each other’s company for a week of hard work?

If the answer is yes, then consider a book sprint. If you’re in the open source world, you may have heard of a code sprint. A book sprint is a similar event, with an intense collaborative authoring session time boxed by a few days or a week. People get together typically in person to author and complete a book in a week.

Generally speaking it’s best if you have an idea of the scope and audience for the book prior to holding the sprint. These discussions can take place on line, such as on a mailing list or in a wiki page or Etherpad. You can also meet with future collaborators regularly, but understand, the first day of your sprint your book will certainly take shape. As book sprinter Adam Hyde says, “While you may not know the exact book you want when you go into the sprint, by the end you will have the book you need.”

For the OpenStack Operations Guide, we held a five-day book sprint in February 2013. OpenStack releases every April and October, and this timing was nearly halfway between two release dates. With Adam as our facilitator, seven authors agreed to work together and we nervously awaited our fate. We asked, “Could we complete a book in a week?”

On Monday we assembled at Rackspace in Austin, Texas, to find out. In a room with an entire wall of white board, we unwrapped packs of paper with fresh markers and started by writing topics on sticky notes. Adam introduced the book sprint process and said that he has done about 55 of sprints. We wrote a note at a time, then a chapter title at a time, a paragraph at a time, a table at a time, a diagram at a time. Sure enough, we collectively wrote about 10,000 words a day, bringing in all the content we could, revising, reshaping, rewriting, until it all hung together as a real book.

About a year later, some of the original authors got together for a two-day mini sprint to bring it up-to-date with the latest release of OpenStack and add an additional reference architecture. In the time between the two sprints, over 30 community contributors maintained the book, reading it, reporting issues, reviewing revisions, and fixing the issues we found. The OpenStack Foundation supported the first sprint costs and worked with O’Reilly to deliver the final product.

Book sprints don’t make you write faster, but they do cause you to create a narrow scope so that you can laser-focus specifically on the most important information. Also a book sprint causes you to think about an audience and their tasks in a way that say, a “wiki cleanup” event wouldn’t.

Does a book sprint with multiple authors make the book disjointed? We got incredible encouragement from our community for attempting this book in the first place, and information came out of it that didn’t exist elsewhere. But there were critics who wanted more polish from the results of that first week. I believe that additional polishing is where the community maintenance makes a huge difference in the resulting book. As many eyes make bugs shallow on a software project, many readers helped us improve the book over the long run. I’m not sure the book completely fought off the criticism of “how can it be any good if it was written in five days” until it went through a developmental edit and multiple critical technical reviews.

Would I do it again? Yes, I would, and I have! For OpenStack we are in the planning stages now for another book sprint this year. We had a book sprint for the OpenStack Security Guide in mid-2013 and it’s due for another release revision. We continually look for opportunities for book sprints while still maintaining our docs like code in the community.

tags: , , , , ,

Get the O’Reilly Programming Newsletter

Weekly insight from industry insiders. Plus exclusive content and offers.