Last week, I wrote about teaching folks to fish. This weekend and in the coming week, I’m spending my time thinking about how to help people be better open source citizens. I’ll be attending (finally, for the first time) Open Source Bridge in Portland, and I’ll write more about that next week. But first, some more practical mental exercises were due on the banks of the Ohio River.

I’m writing this while sitting in Piatt Park in downtown Cincinnati, outside the Garfield Suites Hotel where the 2013 Open Help Conference is underway. A couple of weeks ago, Paul Biondich and I were discussing documentation and stumbled across Shaun McCance and his work organizing these events to discuss the challenges of documentation and support in open source communities. It seemed too good to be true to have such a valuable resource waiting just down the road from OpenMRS HQ in Indianapolis, so Paul and I decided to head down for the weekend together with Burke Mamlin to re-double our efforts to improve OpenMRS documentation.

“Helping people not feel stupid is a major job of documentation.” #openhelp — Shaun McCance (@shaunm) June 15, 2013

We’ve talked for a few years as a community about just how bad our OpenMRS documentation sucks, and if anything it’s nice to be reminded that we aren’t alone in our struggles. But more importantly, this weekend gave us space and time to focus and think critically about how we need to take decisive action to do something about it. OpenMRS is, by necessity, a powerful and flexible platform, and that flexibility often manifests itself as confusing to newcomers, especially given our dearth of useful documentation.

“If you want them to RTFM, make a better FM.” — Michael Verdi quoting Kathy Sierra #OpenHelp
— Michael Downey (@downey) June 15, 2013

This quote from Kathy Sierra is a clear reminder to me about our community’s collective tendency to simply point people to our large collection of documentation and hope for the best. The problem with such an approach is that some of it’s good, some of it’s bad, some of it’s current, and some of it’s outdated. And most of all, most of it’s not structured in an ideal way for people to find what they need, unless they know exactly what they’re looking for.

Saturday evening, the three of us here had a pleasant chat and dinner with Janet Swisher from Mozilla, who helps lead up their developer documentation. We talked about the “chicken and egg” problem about giving people in the community positions of leadership in documentation (with the assumption that they’ll build a volunteer team of writers) … when we don’t have a good pipeline of people making documentation contributions to begin with.

And so, our inclination is to try to build a scaffolding structure of documentation with the help of some generous contributors, along with some examples of what good documentation looks like, and advice for our community on creating it. Our current thinking is that if we make an honest effort at providing some decent resources for potential documentation volunteers, those who come will see some bite-size contributions to get them started and “hooked” in the community, just like our engineering contributors experience.

On Monday, we’ll be reflecting on our experiences this weekend and doing some planning together with Elyse Voegeli, our summer intern from the FOSS Outreach Program for Women, who will be helping us work with our community to start doing some of the highly creative heavy lifting necessary to get there. We’re hoping to help her craft a really rewarding experience in helping us to create the foundation that will help OpenMRS grow very quickly by providing more opportunities for volunteers to contribute—both in terms of documentation and in terms of development. If you feel as hopeful as we do that documentation can make a big difference, an involved already in the OpenMRS community, or if you’re interested in getting involved, I hope you’ll join us.

Writing docs is an “easy in” to almost any open source project @rbowen #openhelp — Janet Swisher (@jmswisher) June 15, 2013

Photo: Robert Blackie CC-BY-NC-SA http://flic.kr/p/3wCnwT