Google DocCamp 2012: Book sprints

LWN.net needs you! Without subscribers, LWN would simply not exist. Please consider signing up for a subscription and helping to keep LWN publishing

There are three new books about free software thanks to Google's 2012 Summer of Code Documentation Camp. The week-long event started off with an unconference, but the main objective was for each participating project to produce a cohesive, book-length work of documentation. All three projects delivered, and thanks to the arrangement made by FLOSSManuals with a local printer, 30 copies of each book were in print late Friday evening. FLOSSManuals has the sprint process down to a science, which is good news for open projects of all stripes, but it is still feeling out how best to sustain the sprint's energy after the participants part company.

The three projects at this year's camp were the integrated library system Evergreen, the educational programming environment Etoys, and the type design application FontForge. FLOSSManuals has been facilitating book sprints in a variety of formats since 2008; the most common format is a retreat where eight to ten project members congregate for a five-day writing and editing session. The Documentation Camp format is a bit smaller in that regard — each team had five or six participants and only three days were devoted to book creation, with the rest spent on a documentation unconference.

One purpose of the unconference was to get the three teams to swap information and share insights and best practices about documentation, but another was to jump start each team's collaboration. As is often the case with open source projects, many team members had never met in person and were used to interacting online. Sharing a small conference room for ten to twelve hours a day and trading edits is hardly common practice. But by the end of the unconference sessions, facilitator Adam Hyde had each team focused on the preliminary steps to writing a coherent book as a group.

Master plan

The teams were first tasked with coming up with a title and subtitle for their books. Although titles can be arbitrary, the brief was more specific: avoid "clever" titles; decide on a clear title that addresses a specific audience. Too broad of an audience or too broad of a scope, Hyde advised, makes for either an unfinished book or one that is sloppy and difficult-to-read. He also advised the teams to pick a topic that would be useful in attracting new people to their respective projects.

I participated in the camp as a member of the FontForge group; although we grappled (too long) to find our eventual title, we did establish our target audience quickly, which provided focus for the book. We decided to write an introduction to the font design process, using FontForge as the example software. Experienced type designers, we decided, can already make some use of FontForge's existing, reference-like documentation. It is certainly imperfect, but, on the other hand, writing a comprehensive FontForge manual of use to domain experts would take more time than was available. At the same time, an introduction to font design would be useful to the interested amateur — particularly considering that FontForge is the only free font design application. Currently, newcomers to the field who cannot afford US $400 proprietary applications either struggle to learn FontForge, or they give up without exploring type design at all.

The other two teams also picked well-defined target audiences and subjects. The Evergreen project targeted system administrators tasked with installing and maintaining an Evergreen installation (as opposed to, for example, library staff members). The Etoys project targeted school teachers wanting practical help integrating Etoys into their classroom curriculum.

With a title and concept in hand, the next order of business was to generate a rough sketch of the book's table of contents (TOC). The TOC is essentially an outline of the narrative, so writing it as a group forces the group to structure the subject matter, work it into an orderly shape, and start deciding where to cut material. That is by no means a simple task, as we discovered in the FontForge group. Type design is a highly iterative process that involves multiple rounds of testing, evaluation, and adjustment; unrolling that workflow into a linear series of steps is fundamentally impossible.

Instead, we had to settle for arranging the workflow into a roughly linear form, starting with a lot of conceptual material for the reader to keep in mind, then do our best to minimize the amount of jumping back-and-forth between chapters. The result requires the reader to get familiar with several parts of FontForge's interface at once (the drawing tools, the spacing tools, the validation tools, and the font generation tools) rather than learning one at a time. That may sound less than ideal, but after several days of rearranging the order of materials, we were at least convinced that it was the best arrangement possible.

Manual labor

The actual writing process occupied about a day and a half, and there is not much to say about it other than that it was what one would expect: gruntwork at the keyboard. All three of the groups had some documentation that they could incorporate and adapt for some of the book content, but for the most part, the content-creation process is writing, rewriting, asking questions of other team members, and building images to use for illustrations.

The software FLOSSManuals uses for book sprints (and other writing projects) is the collaborative editor Booktype. We looked at Booktype's initial release in February 2012. The software has evolved since then, but the basic feature set is essentially the same. It offers a web-based WYSIWYG editor for authoring, supports multiple users, and locks each chapter while an editor has it open. It has a drag-and-drop TOC interface allowing users to rearrange chapters and sections, keeps old versions of every edit, and offers basic statistics on usage participation.

Perhaps the most unusual aspect of Booktype is the fact that anyone can edit any book. This is a conscious decision on FLOSSManuals' part; the goal of the project is to encourage open participation and collaboration. That does not mean it sits well with everyone, though. One of the teams expressed some concern that vandals (perhaps outsiders, perhaps disgruntled community members) would erase or destroy the text. To that, Hyde replied that incidents of destructive behavior have hardly ever happened in the course of FLOSSManuals' fifty-plus book sprints — in reality, he said, it is very difficult to get anyone to contribute at all, and it is extremely rare to see anyone willing to take the time to be destructive. Besides, he added, encouraging positive contributions is a social problem, and building a technical solution for it into Booktype simply would not work. Fellow facilitator Allen Gunn compared it to the open nature of Wikipedia, which had languished in obscurity when editing was the purview of approved gatekeepers only. In any case, Booktype does allow contributors to roll back any vandalism with minimal fuss.

The book sprint editing process involved assigning two proofreaders (not counting the author) to every chapter, and keeping track of their progress on a whiteboard. Since there was a strict deadline at which time the content had to be sent to the print shop, the editing process became quite a rush as well. Hyde advised all of the groups at the outset to avoid the temptation to start writing a "style guide" at the beginning of the sprint, and instead to push stylistic clean-up to the very end.

English majors might chafe at that suggestion, but in reality the proofreading and editing process already involves so much work (including unifying multiple writers' tones with consistency) that it was little trouble to push formatting issues all the way to the end. Hyde made a formatting pass of his own at the end of the final evening, solely to clean up the HTML in Booktype. By late Thursday night, the content was declared finished, and rendered to final output.

Booktype uses HTML internally as its file format, and renders it to various output formats with a transformation engine called Objavi. Objavi can create print-ready PDF, EPUB, Mobi, and a wide variety of other output formats. Hyde created EPUB and Mobi versions of the books immediately, while the hard copies were printed and bound overnight.

Wait for the sequel

The week ended with each team assessing the state of the completed project, and planning how to proceed in the coming weeks and months. Obviously three days is hardly sufficient to cover everything that a quality book would need, much less to proofread and correct all of the typos and human errors. There are also layout issues that can only be revealed after the HTML has been rendered, as well as potential localizations and translations to think about.

Hyde said that his hope was that all three projects continue to refine and update their books, but that it requires intentionality. Open source software is updated quickly, the teams are scattered around the globe, and most participants have day jobs. Add to that the fact that documentation remains an afterthought in many open source projects, and it is all too easy for even a well-written book with motivated authors to get out of date.

The theory behind the camp, after all, is for the projects to learn a different and better way to produce documentation in a sustainable fashion. Although that goal encompasses continuing to write new material, it also includes maintaining the latest book going forward, which is not a simple thing. Hyde highlighted past projects that have excelled at the job (such as the CiviCRM manual and How To Bypass Internet Censorship). He suggested several strategies for transforming the documentation camp book into a sustainable, updated work: how to select a maintainer, how to ask for volunteers, and how to market the book to people outside of the project itself.

All three projects worked on their own plan of attack, and they met together one last time to provide feedback on the sprint process and camp as a whole. Finally, Hyde demonstrated some of the advanced output rendering features of Objavi and showed some of the still-in-development enhancements coming to Booktype.

The response to the camp from the teams was uniformly positive; speaking as a member of the FontForge team, the process was a lot of fun even if it did include a lot of late nights. In addition to producing a worthwhile manual, it was also highly educational to compare notes with other users while hammering out chapters. One team member also observed that the process of writing out the how-to material forced him to distill and organize a lot of information that he carried around in his head, but had never looked at systematically before. That is surely a worthwhile takeaway, and would be even apart from the book.

Nevertheless, the documentation camp produced tangible results of use to readers immediately. You can see all three of the books online (and generate your own output version). The Evergreen manual is entitled Evergreen in Action, the Etoys book is entitled Learning with Etoys, and the FontForge manual Start Designing with FontForge. Only time will tell whether each team continues to maintain and expand its documentation, but I can report that I started receiving emails about expanding the FontForge book before the end of the last night of camp. For his part, Hyde was off to facilitate another book sprint the following week, as part of FLOSSManuals' never-ending campaign to improve free documentation.

[The author would like to thank Google for support to attend the 2012 Summer of Code Documentation Camp]

---

(Log in to post comments)