Open Source Documentation Doesn't Have to Suck

Location: Meeting Room B2
Average rating: ****.
(4.67, 6 ratings)

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


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 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.


Picture of Andrew Oram
Andrew Oram
07/24/2009 4:20am PDT

Good attendance (about 30 people, I think) showed that, even though few people in the audience actually said they do documentation, users and software developers care about its quality.

  • Intel
  • Microsoft
  • Google
  • Sun Microsystems
  • Facebook
  • Gear6
  • Kaltura
  • Liferay
  • MindTouch
  • Novell, Inc.
  • Open Invention Network
  • Rackspace Cloud
  • Schooner Information Technology
  • Silicon Mechanics
  • Symbian Foundation
  • Twilio
  • WSO2
  • Yabarana Corporation

Sponsorship Opportunities

For information on exhibition and sponsorship opportunities at the conference, contact Sharon Cordesse at

Download the OSCON Sponsor/Exhibitor Prospectus

Media Partner Opportunities

Download the Media & Promotional Partner Brochure (PDF) for information on trade opportunities with O'Reilly conferences or contact mediapartners@

Press and Media

For media-related inquiries, contact Maureen Jennings at

OSCON Newsletter

To stay abreast of conference news and to receive email notification when registration opens, please sign up for the OSCON newsletter (login required)

Contact Us

View a complete list of OSCON contacts