Open Source documentation is often evaluated based on its level of suckage, sort of like Dante’s nine circles of hell. We’re going to look at why this seems to be such a problem and ways that we can improve documentation efforts. The experiences, examples and discussion-starters are drawn from the Drupal project’s doc team growing pains over the last year, but the discussion applies to all Open Source projects trying to wrangle usable documentation.
We will start off with a look at why good documentation is a key part of the future success of Open Source. Then we’ll break down some common issues when it comes to providing documentation, specifically for Open Source projects. In looking at various technical and social problems, we’ll see what the Drupal team has been doing (either successfully or not) to address them. Look on with fascination and/or horror at what we’ve tried with various technical tools, live and virtual sprinting, a complete reorganization of content, communication methods and outreach, and general cat-herding/team-building experiments. More importantly we’ll talk about lessons learned and how that is shaping new ideas and future experiments. Where are we getting better? Where do we still need to build a better mouse-trap? Feedback from the audience on their experiences and ideas is welcome and hopefully we can pick up and share information that will equip us all to make Open Source documentation a shining example rather than an assumed liability.
Addison Berry has been involved with the Drupal project for about 3 years and is the current Documentation Team Lead. She works for Lullabot, an Open Source consulting and training company that specializes in Drupal, and is a co-author of O’Reilly’s “Using Drupal” book. She helps maintain the Drupal.org website and is a permanent member of the Drupal Association General Assembly. In addition to her focus on documentation, both written and video, she is involved in core and contributed development, and has been involved with mentoring programs such as the Drupal Dojo and Google’s Highly Open Participation (GHOP) program.
Comments on this page are now closed.
For information on exhibition and sponsorship opportunities at the conference, contact Sharon Cordesse at firstname.lastname@example.org
Download the OSCON Sponsor/Exhibitor Prospectus
For media-related inquiries, contact Maureen Jennings at email@example.com
To stay abreast of conference news and to receive email notification when registration opens, please sign up for the OSCON newsletter (login required)
View a complete list of OSCON contacts