by How long does it take to write a 116-page manual introducing Evergreen administrators to basic setup, configuration and maintenance? If you bring together a dedicated documentation team, great facilitators, and the right environment, it turns out you can do it with just three days (or closer to two-and-a-half days) of focused writing.
I had the opportunity to work last week with four of my Evergreen colleagues to create such a manual. Traveling to Mountain View, California, I joined Robert Soulliere of Mohawk College, Lindsay Stratton of Pioneer Library System and Dan Scott of Laurentian University for the Google Summer of Code Documentation Sprint Camp. Our final team member, Jim Keenan of C/W MARS, could not make the trip, but joined us daily via Google Hangouts to make his contributions to the effort.
Evergreen was one of just three open-source projects invited to participate in the doc sprint. The other two were Etoys, a child-friendly programming language for use in education, and FontForge, an outline font editor that allows users to create their own fonts.
On day 1, Allen Gunn (Gunner) of Aspiration facilitated an unconference where participants collaborated on topics like keeping documentation up to date with rapid development, user communities, documentation tools, and documentation-driven development. The unconference helped the participants become comfortable with one another in speaking freely about their ideas and opinions and began the team-building process that continued through the rest of the week.
By the end of the first day, the team had created a title and tagline for our future book: Evergreen in Action: So you’ve installed Evergreen — now what?
The target audience for the book is Evergreen administrators who have successfully installed Evergreen and now need to load data and configure the system. The goal was not to provide a comprehensive overview for each possible configuration option in the system, but to present the basic steps required to get up and running, focusing on common use cases.
With the basic framework in our heads, we entered day 2 with what was to be the most difficult part of the process: creating a table of contents for the book. Adam Hyde of Floss Manuals provided guidance to the teams as they progressed through the process of shaping their books.
We wrote our content ideas down on sticky notes and tried to arrange them in a logical order, a difficult task when so many pieces of the system are interconnected with each other. By lunchtime, when the table of contents was supposed to be finished, we still had far more chapters than could be completed by a team of five people in less than three days.
The team then needed to go through the process of “killing our darlings,” dropping some desired chapters from the manual, but also leaving an opportunity for others in the community to contribute their knowledge and expertise at a later date.
Once the table of contents was completed, the next 2 ½ days fell into place as each of the team members wrote their chapters. They were long days, but the team worked well together, focusing on their areas of expertise while periodically asking questions of each other or even sometimes consulting the always-helpful IRC community.
The team’s strength was the diversity in skills among its members, leading to a fuller and richer manual, just as the diverse skills in the larger Evergreen community have led to a stronger ILS and vibrant support community.
With the book done, Gunner facilitated another unconference on the final day where we talked about ways to sustain the work we started at the conference. Keeping the manual updated should follow the same processes used by DIG to keep the documentation repository up to date, but we would like to see closer ties between the development and documentation process.
If the development community added an additional check to the sign-off process where release notes must be included with any new enhancement before the code can be committed, we could ensure release notes are complete at the time of the beta release. A DIG volunteer could then review the release notes for accuracy and readability. Those release notes would then form the basis for changes in the documentation.
Future doc sprints organized through the Evergreen community are wonderful ways to keep up with and expand our documentation efforts. The hackfest day at the conference is useful for small updates and tweaks to the existing documentation, but multi-day sprints could lead to other task-based manuals like the one we just created.
Including DIG participants at developer hackfests could tie the two processes more closely together. At the same time, we should schedule some doc sprints at times when developers are not hacking since there are community members who straddle the developer and documentation worlds. The five community members who have now participated in a successful model for a doc sprint can lead the way in making these sprints happen.
I want to send along a final thanks to Google Open Source Program Office for sponsoring the program, to Allen Gunn for getting us energized, to Adam Hyde for guiding us through the book-creation process, and to all those in the community who answered our questions throughout the week.