Notes taken at OSCon concerning documentation for open source A session was given by Addison Berry, presenter Open source isn't hacking for hackers any more. Documentation is crucial to getting open source to spread beyond this point. Documentation for developers too--we need to make it easier for people to come in. Challenges: Wide variety of people (cultures, backgrounds, perspectives) which lends itself to miscommunication and conflict. They're also unorganized. Mismatched skill sets: you have to use whoever came to you. Volunteers: they'll do what they want; you can't tell them what to do. And their energy comes and goes. If someone loves writing code but won't write documentation for it, project leaders have to deal with it. Expectations and standards are very low for documentation. People tend to think that documentation is like sex: when it's good, it's very, very good, and when it's bad, it's better than nothing. Unlike rigorous quality standards for code that goes in the core, almost anything is accepted as documentation. But actually some documentation is worse than nothing. Opportunities: The wide variety of people is also an opportunity. Rich source of ideas come from people poking around, often without pre-existing knowledge. May discover wonderful skills you never expected among volunteers. Open source is a great place to learn, so can attract people who want to do things to learn more. You can explicitly suggest tasks and describe what people can learn from doing them. You can harness people's love of coding, writing, etc. Someone has to be able to work in a team in order to succeed in open source, so you'll find people self-select who are good at working in teams. Experiments at Drupal: Removing barrier to entry: A year ago, anyone who wanted to do as little as fix a typo would have to create an issue requesting to be on the documentation team and get permission to join. Changed process to allow anyone opening an account on Drupal.org to edit, like a wiki. A little spam, but lots of useful fixes. Drawback: No line any more between who is on the documentation team and who isn't. Hard for new people to figure out who is responsible and how things are done. Doc sprints: are doing it a lot, both physical and virtual. Attendance is increasing. They're still figuring out better ways to coordinate. Addision is traveling a lot and sitting down with volunteers to show them what they can do. Increases participation by making them comfortable contributing and knowing what to do. Roadmaps: dissents from common view that volunteers have to find their own ways forward and that an open source project can't provide roadmaps. Distributed responsibility may work for code, but documentation needs a roadmap. Spent weeks deciding what the project needs and prioritizing it, then tell other people what to do. Roadmap was released a month ago and was well received; will need another six to twelve months to know whether it's successful. Better ways of communicating: traditionally depended on mailing list and issue queue. Some people arent comfortable with that, expect web forums. So starting now to blog, add news to the landing page, use Google Grouops to schedule meetings, have IRC channel anyone can join to discuss Drupal documentation. Goal is to provide any means of communication that improve participation without fragmenting the community by providing too many channels that don't connect. Some success: people are talking more. Lessons learned: Cheerleading is really hard, but you have to do it. Have to communicate regularly about what you're doing. People don't really care about documentation, so keep it in their face. This is necessary to keep documentation sustainable--little value in producing a great document that isn't maintained. Community is critical. Need a constant influx of people to update and write new docs. So take just as good care of the community as the words on the page. So the roadmap has two lists of priorities, one for community and one for documentation. Find the right job for a right person. Build new leadership. As doc team leader, Addison spends about 10% doing actual doc work and the rest of the time on people. This may shift more toward doc work if she succeeds in building the team. Have goals. Benchmarks, even random ones, get people excited when they are met (or even if you get close). Metrics can tell you how effective you are. Future: Will start work on peer-to-peer mentoring. Reworking documentation architecture based on research down by student volunteer about usability of Drupal site. What's going on in the open source community: Writing Open Source conference. http://writingopensource.com is open to anyone. Just as a single author can't fix a project's documentation without the help of a community, no single project like Drupal can improve without the help of the other projects. Need to share ideas and needs. Addison blogs at http://rocktreesky.com, add1sun on Drupal, Twitter, and other networks. --- Design Patterns The original Gang-of-Four book could have been titled "How to Make C++ Suck Less." Many other languages make it easier to implement the patterns than the solutions shown in the book. Some patterns subsumed into language or common library constructs. Builder pattern: nice to let people build in any order. All they have to do is specify a new function and the missing-method feature of a dynamic language implements the function by invoking each individual builder function. Implementor: Based on building a powerful language out of a weaker one. Now is implemented by building a domain specific language. Can assign a new method to basic objects such as integers in some dynamic languages such as Groovy. But needs to handle different types, such as integers and floats; calls this type transmogrification. Ruby can reopen a class to add a new method. But will override the old one if a method of that name exists, using an alias. So you can also rename an old method, and the new name will invoke the old method. Compilation can be considered premature optimization. Groovy is compiled, so less flexible than dynamic languages such as Ruby, but you can hook things in during the compilation. Nulls: Require special handling in Java and other older langauges. It's just an object in Ruby, so you can just ask whether the object is nil. Arridifier: To Remove duplication, define a pattern and pass it to a method that applies the common operation. Dynamic languages tend to use language facilities to keep you from the need to keep defining new classes. --- Birds of a Feather on open source software documentation Addison also led, along with Emma Jane Hogbin, a BOF where they discussed the Drupal experience along with more of the themes of the Writing Open Source conference. There were two main topics aside from the material on Drupal I wrote up from Addison's talk. First, we introduced FLOSS Manuals and encouraged people to try it. I brought up the wiki on a laptop and passed it around. Second, I posed my view of many small docs updated on scattered sites as an alternative to the Drupal approach that Addison had described in her talk. The Drupal doc team is trying to get organized and coordinated, which I respect. But redesigning their architecture, defining a roadmap, and writing a style guide (a topic that didn't come up during the formal session I wrote up) are all very centralized. I joked that they sounded like a publisher. I presented a few of my ideas about finding out from log files what people want, putting editorial effort into the most popular topics, etc. Addison said that decentratlization hadn't worked for them; they had been talking in circles for years and only now were they starting to make progress thanks to the central effort. We agree that being smart, conscious, and goal-directed are importance. There are just many ways to be those things.