Google Summer of Code Book Sprint 2013

Or how I learned to stop worrying and write a book.

Last week, I flew down to Mountain View, Ca for the Google Summer of Code Book Sprint. It is an event that brings open source projects together to write a book in a week. 20 people and 3 projects produced books over a sunny and well-fed week. Kindly hosted by Google, we spent 5 days hanging out at their campus writing away. The three projects involved were:

  • OpenMRS - A medical records system used in many developing countries, originally created to help with AIDS in Africa.
  • BRL-CAD - A CAD program for developing 3D models, one of the first open source projects from the United States Military.
  • Mallard - An XML based documentation framework, from the Gnome Documentation Team.

I was what they called a “free agent”, someone not involved in a specific project that would help out. Free agents are useful for providing an outside viewpoint to the projects.

Writing a book was an amazing experience. It has always felt out of my reach, but time limiting it to a week (really 3 days), made the goal more approachable. I hope this post will help you conceptualize the process of how we wrote the book, and possibly think about doing it yourself. After this experience I think it is something that anyone can do, as long as you keep the scope small.

You can see the finished book for OpenMRS online.

Monday

Heresy

On Monday, we got together to play some games to break the ice. We were asked to write our most polarizing documentation viewpoints on an index card, and they were read out loud in front of the room. People arranged themselves along a spectrum of agreement and disagreement. Physically arranged themselves, by walking to different corners of the room. Then we presented reasons for our views on the topics mentioned.

Some examples are:

  • Developers MUST write documentation
  • WYSIWYG editors are evil

This exercise acted to show how diverse a crowd we had. Some people were developers, some were tech writers, some were students, some were teachers, people ranged all across the spectrum of experience. You learned to respect where people were coming, which might be very different from your background.

Audience and Outcomes

After the ice breakers, we did an exercise where each member of the team was broken into a separate group, and had to write down their views for the book. We were told to have up to 3 audiences in mind, and 3 take aways someone would have from reading the book. This allowed people to flesh out their idea of the book without other members of their team present. The idea behind this exercise was to eliminate the group-think that happens when a group works to shape an idea. It also allowed us free agents to get an idea of what book people were writing, and which we might be able to help out with.

Once we all fleshed out our ideas individually, the groups got back together and talked through what they thought the book should be. This is the stage where free agents chose their team as well, so that they could see the vision for the book.

As a project group, we then chose the audiences and takeaways for the book. This is the part where I joined the OpenMRS group. They were writing an introductory book for developers who wanted to get involved in the project, and I felt I could help out as a developer coming to the project fresh.

We assumed everyone would be new to OpenMRS. We then broke this down into 3 types of things people might be new to:

  • Developers new to Health IT
  • Developers new to Open Source
  • Developers new to Software Development in General

The outcomes we wanted people to come away with were:

  • Understand how to become a member of the OpenMRS community
  • Be able to get the OpenMRS environment set up
  • Feel confident doing development on OpenMRS modules

Tuesday

Table of Contents

On Tuesday we got together in the morning to come up with a table of contents based on our audience and outcomes. Having the audience and outcomes written down really helped guide and focus the book. At each step someone could ask “is this really serving our intended audience?” We only had 2 and a half days to actually write, so we needed to aggressively trim the content to something that we could accomplish in that time.

Our table of contents ended up looking like:

  • Introduction
    • Welcome to OpenMRS!
  • Saving Lives With Software
    • The Need for Health IT
    • Our Response
    • OpenMRS Today
  • Community
    • Working Cooperatively
    • Collaboration Tools
  • Technology
    • Architecture
    • Data Model
    • Development Process
    • Get Set Up
  • Case Study
    • Creating your First Module
  • What’s Next?
    • Get Involved
    • Get Support
    • Developer Checklist

Promotion Plan

We also talked through a plan to release the book into the community. There was an understanding that if you don’t promote the book, the time spent writing it might go to waste. Having a way to build momentum for the project in the community would ensure the book continued to live on after this week.

Our original promotion plan looked like:

  • Blog post announcing the book on the project blog
  • Tell developers in the project about it, so they can recommend it to people
  • Add it to all of our beginner documentation
  • Talk with existing developers to make sure the information in the book is correct
  • Add a JIRA project so we can track issues with the book
  • Add a survey so that we can get feedback on the book
  • Make sure that updating the book is added to release processes

Compare and Contrast

After coming up with ideas inside our own teams, we sent a member to each other team to hear what they had come up with. We were encouraged to steal their ideas if they had something interesting, and to provide feedback if we saw something missing. This worked really well at removing group think again, and making sure that you didn’t have a huge blind spot in your plans.

Start writing

After lunch on Tuesday, it was time to start writing. This part was referred to as “content production”, there was a specific focus on just getting pen to paper. Editing would come later. We worked until 8 in the evening, and then headed back to the hotel.

Around the pool that evening we spent time hanging out and talking about ideas. In particular I talked to the Mallard team, comparing and contrasting it to Sphinx.

Wednesday

Content production continued Wednesday. The goal was to have a complete book by Wednesday night, and then spend Thursday refining and editing it down.

Thursday

Thursday was spent writing until around lunch, then the afternoon was spent editing. We formed groups of 2 or 3 which looked over a section at a time. Each section had an average of 3 chapters, and you looked to make sure the flow of all the chapters made sense together. We would each read a chapter and then talk over each of the issues that we found.

At 6pm on Thursday we called the books done, and all celebrated.

Friday

On Friday we got together to do a postmortem on the process. We talked again about the promotion plan, assigning items to specific people to make sure they got done.

This was all along the theme of continuing momentum forward. We now had a list of tasks, with people who were responsible for getting them done. This made me feel a lot more confident that our work would live on, and really make a difference in the community.

Take aways

I think the mixing of ideas behind groups was really key to success in this endeavor. Group think is potent, and having someone with an outside perspective come in can really reveal your blind spots.

Along these lines, the evenings hanging out by the pool talking through your work was really important. You can’t sit and write 24/7, and having a place to escape and let you ideas breathe really allows you to form them. I think throughout the week everyone was thinking about their book pretty non-stop, but were weren’t necessarily writing non-stop.

I come away from this experience with a lot of inspiration and perspective. Writing a book is something that anyone can do, with a little help from their friends.



Hey there. I'm Eric and I do consulting and provide other services around software documentation. Feel free to email me if you want to chat.