Monthly Archives: October 2011

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


wiki writing

Wiki Best Practices from Wikia Content Team

I found this great set of best practices for wikis on the Wikia site. They host 275,000 wiki sites on all sorts of topics, and truly want to help people reach the most potential with their wiki by offering guidance. One of the pages lets admins of a Wikia wiki ask the Content Team for specific help. Here’s a direct quote from that page:

We’d love to help attract new contributors to your wiki. If you’re interested in working with us on optimizing your wiki, we’d like to be sure you’re following a set of best practices.

  • The requester should be either the admin, or link to a discussion with the admin of the wiki and agreeing to skin design and homepage help
  • The wiki should have at least one active admin, meaning he or she has made at least one edit in the last 7 days
  • The wiki should have at least 50 content pages, not counting stubs. Stub articles should make up no more than 1/5th (20%) of all pages on the wiki
  • The wiki should have a clear category structure to help readers navigate around the site. Every content page should be in a category
  • The wiki should not be in the middle of choosing new admins, or any other upheavals. It should be a stable, friendly place
  • The wiki should be using the Wikia welcome tool, signed by admins — (MediaWiki:Welcome-user should say @latest, @sysop or the name of an admin)
  • The wiki should not use offensive language or include inappropriate images.

The Content Team will make all final decisions and design work will be at their discretion. If your wiki meets these criteria, leave a message on the talk page of this article.

The Content Team appears to call this criteria the bare minimum for calling your wiki a wiki, based on activity (must be updated at least weekly) and have at least 50 pages containing real content, not just part of an outline.

What’s interesting to me is that this team realizes that the people are as important as the content. Without consistent people and a proven way to welcome more people, the best practices aren’t met.

Lots of people ask for wiki best practices – these are a broad set for multi-purpose wikis on topics from video games and TV shows to food and fashion. It does offer a bar to reach for any wiki.

work writing

Docs in 2031

I like to think about the future of documentation, ruminating on future processes, interactions, and tools. Yet this past week at the OpenStack Conference I was faced with the reality of the future of documentation as a storage device for knowledge. A long-term storage device, as in, 20 years from now, people (scientists, to be precise), will need documentation to retrieve important scientific data collected in 2011.

We had a few user stories at the Conference this year, and I was blown away when Tim Bell told the story of how physicists wake up each morning and ask questions about the basics of how the universe works. In the process of asking and answering basic questions the fundamental particles that make up our world, they collect 25 petabytes of data a year. And here’s the future part – they have a service level agreement that ensures their scientists can have access to the information for twenty years. And here’s the docs part of that – we’re tasked with maintaining API documentation that can enable the access to data and replication of a cloud computing platform that can process the data. If you don’t provide the magical incantations to retrieve and process your data, the service agreement is broken.

The presenter Tim Bell said he sometimes receives emails intended for Sir Tim Berners-Lee, the inventor of an information management system that enabled physicists to send information to each other, now known as the World Wide Web. He supports scientists who take pictures of what happens when tiny particles collide with each other at nearly two degrees above absolute zero. His was an inspiring and intimidating talk all at once. Updated to add: here is a link to his presentation on Slideshare, CERN User Story.

Flickr user Ernst VikneI have to admit, I believe using an XML standard like DocBook, which was invented in 1991, helps us future-proof the docs. Not that I’m over-confident either, it is quite intimidating to provide docs to the scientists of 2031. Perhaps even the college-graduation class of 2031, those future students who are toddlers today, will need to spin up virtual machines in order to replicate systems from 2011. With dedication, collaboration, and hard work, the site will be available. With the creation of an OpenStack Foundation, we look towards the long term, not the short, and plan to keep the docs ready for those who will need them in the future.

If you’re the type of person who is inspired by such documentation efforts, I’d encourage you to take a look at how the docs are made and collaborate with us. You now know how long-lasting your documentation efforts can be.