Google DocCamp: documentation unconference

Google played host to its second annual "Summer of Code Documentation Camp" at its Mountain View offices over the first week of December, at which teams from three free software projects gathered to sort out and write sorely-needed documentation in an intensive workshop setting. This year's participating projects were the Evergreen integrated library system (ILS), the Etoys educational programming environment for children, and the open source font creator FontForge. During the last three days of the camp each team was tasked with producing its own self-contained manual through a "book sprint," but the first two days were composed of an unconference-style workshop about tackling the challenges of documentation in an open project.

Despite the name of the event, the camp is a distinct entity from Google's university-oriented Summer of Code mentorship program (although warm in December, Mountain View is demonstrably not in the Southern hemisphere...). But the two programs do share a common theme. The facilities and amenities were donated by Google, but the week's activities were run by Adam Hyde of FLOSSManuals and Allen "Gunner" Gunn of Aspiration Tech. FLOSSManuals, of course, is a project dedicated to enabling and encouraging open source communities to write and publish quality documentation; Aspiration Tech is a training and consulting group focused on working with nonprofits and software.

Unconferring

The unconference portion of the week consisted of a series of breakout sessions exploring documentation-related subjects. The unconference format means, first and foremost, that the agenda for the sessions is not fixed in advance, but is created by the participants during the event itself. The result is a program that tackles the specific needs of the participants — which, considering the time constraints of the week, was especially important.

Gunn first led the participants in a series of brainstorming exercises in order to generate a pool of topics of interest. The participants then read through all of the suggestions and attempted to group them into recurring subjects. From the resulting ad-hoc taxonomy, Gunn and Hyde selected the initial breakout session topics. But after the first round of breakouts was over, it was up to participants themselves to facilitate the sessions, exploring the topic at hand and deciding what (if any) additional sessions needed to follow later in the day.

At first glance, it might seem like the three projects represented at the unconference would have very little in common to discuss. Yes, every open source project struggles with writing documentation, just like every open source project struggles with recruiting new talent. But the projects themselves differed considerably in scope, purpose, and technical detail. Evergreen is an integrated, server-based application suite with a web interface, used and managed by a very specific type of professional institution. Etoys is a self-contained interpreted programming environment designed for classrooms and tailored toward young children. FontForge is a graphical desktop application used for an isolated task typically undertaken only by specialists.

But the brainstorming exercises quickly revealed that the projects grapple with a nearly identical set of documentation challenges. All three struggle with accessibility and translation tasks, all three have difficulty integrating updates to documentation with updates to the codebase, all three have trouble setting up and maintaining a workflow among documentation volunteers. Consequently, in each breakout session (there were three or four simultaneously during each session slot) Gunn ensured that there was at least one representative from each of the three teams, so the teams were able to exchange information and learn from each others' experiences.

Prep work

None of the session topics lent itself toward simple "how to" answers. Rather, the goal of the breakouts was to prime each group's thinking on the documentation tasks, in preparation for the writing portion of the week that followed. But there were still insights to be found in each discussion.

For example, in the translation session (in which I participated as a representative of the FontForge team), it came out that all of the projects have found success with open source tools for translating application strings and in-program help messages: Pootle, Launchpad, and other tools handle this task quite well, providing an overview that indicates the percentage of translation completed for each available language, offering translation suggestions based on other projects' work, and so on. But none of those features are available in the systems that projects use to maintain their documentation. These string translation tools are designed to handle short snippets of text only, and typically fail on paragraph-length content: long sections of text do not fit into the boxes in the interface, and the features that track completion expect the entire text to be translated at once (which is rarely possible or desirable with lengthy discussions). Conversely, the content management systems that support multi-lingual web sites do not offer the percentage-completion tracking or suggestions that make application translation more manageable.

The other topics examined during the breakout sessions included soliciting and incorporating audience feedback, iterating and versioning documentation, developing and maintaining a healthy community of documentation writing, finding tools to support remote documentation efforts, and many more. By Tuesday, however, the program shifted away from general topics and toward the specifics that each team needed to address for its own book sprint. This meant nailing down a specific target audience and drafting an outline of what subject matter would be covered, start to finish. That can be a daunting task, particularly in light of the knowledge that only three days will be available for content creation and editing, and with teams of only five or six people.

The writing itself began in earnest late on Tuesday, and although the deadline still looms large and ominous, it is remarkable how quickly the work starts to take on a concrete shape. But that is the secret that FLOSSManuals has set out to share with the free software community: writing documentation may seem hard, but then again writing software is hard, too. And just like writing software, once the community sets its mind to the task, it can accomplish considerable feats. That lesson does not end on Friday, either; already there has been talk among the projects about what subjects ought to be tackled in future book sprints. Even though Evergreen, Etoys, and FontForge will walk away from the week with a new book, hopefully the lesson will not be limited to just those three projects, either.

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