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.
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
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.
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
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]
to post comments)