Google Summer of Code Doc Summit Stories

On my way to the airport after an intense and enjoyable three day session with four open source projects writing a book apiece, I wonder if I have any more words to write down. The group I worked with had 14,000 words in the system by day two. I feel I need to try to capture this experience. I’m feeling a little badly about coming home early – they are still working hard at it today!

The four projects were KDE, OpenStreetMap, OpenMRS, and Sahana. Each project brought 3-5 participants. Some of the participants didn’t know they had applied to write a book in three days. One project already had a long outline, reviewed by other community members. The participants’ backgrounds varied widely – tall, wide Python developers with long hair in a ponytail, disaster managers with cropped hair and glasses, a geology professional with a travel bug, cycling data wranglers and web developers, C++ developers and young gamers, a user advocate who also happened to be a grandma, and then there were the doc aficionados who find all of this quite fun, like me.

We all started the week with an unconference led by Alan Gunner from Aspirations technology, who has a way with words and a distinct gift for engagement. No one hid behind their laptops (though sneaking a peak at a small screen like a mobile phone did happen sometimes). About thirty of us were gathered, and I feel I’m leaving with a sense we have built a community of practice, that I can contact any other attendee to talk docs. What a valuable gift from Google, whose Open Source group funded the week with lodging and food provided.

Story telling

People were quite transfixed by the idea that a book can tell stories. Part of uncovering a story to tell involves audience discovery. FLOSS Manuals community members like Janet Swisher led the teams through an audience analysis exercise. These were her questions:

  • Who is using your tool?
  • Why do they use your tool?
  • What kinds of things are they trying to do?
  • What can you assume they know?
  • What do they probably not know when they approach your tool?

For these exercises, free agents like myself were assigned to one of the four teams. I went to the Open MRS team, which provides medical record software for developing countries. This was a great chance to learn how open source affects human lives. I learned how important it is to know who is setting up their software and why. Turns out, the majority of the project’s communication is with people who want to build a module for OpenMRS in their specialty domain. There are also implementers who want to use OpenMRS as a data store, turning their paper input forms into a form the registration desk can use when a patient reaches the front of the line at the clinic. They’ve also recently seen an uptick in requests to integrate with the OpenMRS platform, such as inquiries from Doctors Without Borders.

Parts of answering the “who” question also led to answering the “why” question – they use the tool because they need some extension of clinical functionality, they need a customization for a particular strain of drug-resistant tuberculosis, or possibly just because “their boss told them to” which then leads to investigation of why their boss wants to use OpenMRS. Mobile data entry and data retrieval as well as language support were parts of the reasons why they’d choose OpenMRS. Some of the stories that came out were not yet well-articulated, but discussing real people with real work was a huge help. I envisioned implementers taking an input form and making an online form, studying the data model while they did so. I heard about patients not making appointments but waiting in line for hours at a registration desk where they would be received for an observation by a medical professional, I wondered about the person accepting shipment of boxes of medicine. These every day tasks capture your attention and hopefully can be translated into a better, more engaging read.

Wiki writing vs. Book writing

On the morning of our third day together, one of the participants made a fascinating observation about the process of writing a book – that he actually approached the act of writing differently this week, with more focus on completion and quality, since he wasn’t writing in a wiki. In a wiki, he expected to be able to write in an outline, freeform, and someone would come behind him, he assumed, and make the text better. But knowing that the final deliverable was looming at the end of the week, he wrote more carefully with an audience in mind when he wrote in the FLOSS Manuals booki tool. This single observation captured my attention. How many others feel this same way when they contribute to your project’s wiki? I tend to avoid that problem by strictly stating what information goes into the wiki, in hopes of also focusing better writing attention in other areas, I guess. But what about writing for a linear, printed book, versus writing for a website where every page could be the first page? I believe us practiced pros know we can improve upon the classic act of writing by writing for personas and telling stories both for a book deliverable or an engaging user experience on a website. But it is certainly a tough task to coach others to do so. I felt that the book sprint experience, compressed and yet with elongated days of intense collaboration, was a great method for coaching improved writing in others.

Result: Books

Three of the four books are now available on Lulu. The covers look fantastic! Congrats to all the authors and many thanks to Adam Hyde of FLOSS Manuals, the Google Open Source Programs office, and everyone who took the time to make these books shine.

OpenStreetMap Sahana Eden

KDE Guide



  • Karen Kay
    October 22, 2011 - 12:46 pm | Permalink

    I am really glad that you talked about documentation telling a story. I think that’s an underrated tool–I know very few technical writers who approach documentation that way, but I think it makes sense to developers.

  • October 24, 2011 - 5:06 am | Permalink

    The “OpenStreetMap” book cover at the end of your article is linking to the Sahana Eden book at

  • October 24, 2011 - 7:41 am | Permalink

    Thanks Claudius, now fixed. Appreciate it!

  • Pingback: Suomen FLOSS Manuals » Neljä kirjaa kolmessa päivässä

  • Pingback:   Weekly links roundup by Communications from DMN

  • DS Hendler
    November 15, 2011 - 11:14 pm | Permalink

    For me, the concept of personas and telling stories go hand in hand. But when I have explained to others how I use personas in writing or testing, they tend to think it’s a rather strange concept, or a concept too difficult to undertake. I’m curious: how do you get writers–especially those tasked for a book sprint–to go along with it?

  • Pingback: Neljä kirjaa kolmessa päivässä « FLOSS Manuals (Suomi)

  • Leave a Reply