Below is a guest post from Kathy Lussier, an Evergreen participant describing the process of this fast and furious way to collaboratively write a book on software documentation.
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.
Lindsay Stratton (from left), Robert Soulliere, Kathy Lussier and Dan Scott at the Googleplex for the Google Summer of Code Documentation Sprint.
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. 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.
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 enabling them to speak 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 two 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.
Jim Keenan contributed remotely via a Google Hangout.
Once the table of contents was completed, the next two and a half 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. Our 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.
I want to send along a final thanks to the Google Open Source Program Office for sponsoring the program, to Gunner 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.
By Kathy Lussier, Evergreen Contributor
Google is excited to support the need for good, clear documentation of free and open source software with the three projects this year as well as the four projects from last year’s successful Document Sprint.
By Stephanie Taylor, Google Open Source Programs
