What would a rockin' docs year look like?

This year is already shaping up to be busy and challenging in a lot of ways, but one the biggest challenges I'm chomping for is in the world of documentation. By "world of documentation," I don't just mean Drupal docs either; I'm talking about all Open Source docs. Here is a bit of a glimpse into my visions for 2009. Put yer doc goggles on, cuz I'm on a wild ride.

The main focus of a lot of my work will, of course, be on Drupal. We have an awesome redesign rolling along and a lot of work to do. While the work obviously needs to happen, I want to focus a lot of time and energy on an over-arching goal for the year: get people engaged. The work needs to get done and we need people to do it. Open source is great because anyone can get involved and Drupal has an amazing, strong community. That said, a common sore spot in Open Source is making paths clearer and lighting the way for people to get involved. I know I harp on this a lot, but it is really important, and we can do better. I'd really like getting involved with documentation to be clearer, for folks to feel more sure, and as a result, for the whole thing to become more viral. Most of the time it doesn't require much more than just giving encouragement and confirmation. A lot of people already know how to do the tasks, but they aren't confident in the process or that they are "doing it right." Spending even a small amount of time to write better docs or talk someone through something pays off in huge rewards.

To that end, I've started a few things already and I have bunch more planned. New ideas are also welcome and, of course, anyone should feel free to take off with ideas on their own too.

  • Monthly challenges: I've already kicked this off for January and I intend to run it all year. The basic idea is to pick a specific docs task to focus on for an entire month and provide guidance to folks who would like to get involved or learn more. This mainly requires providing a clear goal, channels for questions to be answered and dedicating some time to the task at hand.
  • Sprinting: this is where things can get seriously viral. I'm going to plan and attend as many doc sprints as I can fit in this year. Hopefully the Knight Foundation will facilitate a lot of it. When I do sprints, I don't want to just "do docs," I also want to teach others how to set up their own sprints and really keep the camaraderie and support going. Even if I can't get to as many physical places as I want, I'm also going to make myself available virtually to Drupal events who want some guidance running sprints.
  • Documenting how we document: this may sound weird or meta, but if we want people to help document Drupal, we need to make it super clear how to do that. The documentation about docs has improved a bit recently but it still needs quite a bit of love. I really want the things we learn from the challenges and the sprints to make it back into our own docs. Not everyone can get real-time help so we need our docs to step in for us and be a solid resource.
  • Recruiting coders: many people who love the code have a knee-jerk reaction to avoid or dismiss helping the project's documentation. No hard-core h4x0r is going to be caught dead writing docs, right? ;-) For some folks, writing docs just isn't a good match, but coders can help docs out and not lose their bad-ass persona. We will really need honest-to-goodness coder skills this year. The docs team needs tools. Writing is all good and well but making it easy to submit, track, organize and translate all of this stuff requires some code. We need you and your bad ass.
  • Redefining the "docs team": this has already started and not just because I said so in an email. We opened up editing on Drupal.org last year and so the reality is that there is no barrier to "being on the docs team." Everyone who is listed under our contributors is on the docs team, not just in my opinion but in reality. Stating it clearly and strongly is important for many people to change their perception and I want to carry this message in all of the Drupal docs work we do this year. If you have a Drupal.org account, you can officially be on the docs team by simply editing a page.

Another personal goal for me this year is to tap into the larger Open Source community. We all need to document our work and most OS projects run on volunteers, just like Drupal. How are others approaching problems? What can we learn? What can we share? So I've got a few things on radar to explore these places, with the idea that these are just the start of a broader, long-term exploration.

  • Writing Open Source Conference: this is a little idea that Emma Jane Hogbin talked about with me and, along with Belinda Lopez, we've decided we are going to go ahead and make it happen. There aren't a lot of documentation specific conferences out there to begin with, but there is nothing at all focused just on Open Source documentation. We really need to get together and talk shop, people. So, we're going to do an unconference and sprint in Canada this summer. We'll have more details flowing about it soon, but I am reeeeeally excited about this.
  • OSCON: I have a proposal submitted for this classic Open Source meeting ground, titled "Open Source documentation doesn't have to suck." Even if it doesn't get accepted, I plan to attend and rally even more Open Source docs folks together to share ideas and help each other out. "Watch out for that crazy Drupalista."

So my year is already revving up. What's got you jazzed up about 2009 in the Open Source world?

Comments

I don't think that "more docs" is the whole solution to Drupal's documentation woes. Documentation needs to be findable in order for it to be useful, and we need to be able to browse documentation on Drupal 4.7 and Drupal 5, even when we're using Drupal 6 day-to-day. The existing docs structure lacks adequate ways of versioning, organizing, and tagging documentation.

One way to address these things would be to reinvent the navigation based on existing tags and menus; another would be to separate "core documentation" out into a canonical, versioned set of docs which can be marked "stable" at certain points, and to treat the rest of the docs as a community area.

Personally, I think it would be fantastic to have "core documentation" as a project in CVS, with its content mirrored and open for comments on drupal.org. Along side this, it would make sense to encourage projects that currently keep some documentation in the handbook (ie, CCK's hooks documentation) to maintain this as part of the project itself.

Yep, I agree with you 100% and the biggest part of the redesign for me is to address those underlying issues. In my post I didn't want to get in to the nitty gritty of the work to be done because I wanted to focus on higher level ideas, but like the reference to needing coders, I am talking about rallying people to work on *all* of the issues we face, not to just to write "more docs."

You might want to check out the last iteration of the redesign and some of the extended discussion about rethinking docs, which is very tag-based and trying to look at the best way to do things like versioning.

One of the technical things that we will be focusing on at the next docs meeting (this Sunday, Jan 18) is the patch to get a new Help system into core for D7. Once that settles, next thing on my list is to look at how we can leverage that system for documentation on Drupal.org as well. Getting docs in to CVS has been approached various ways that have not been successful so far. This year we do mean to find a sustainable solution to just that. I even have a proof of concept module for D6 that provides basic docs using the Advanced help module (and therefor can be checked into CVS and used as a regular module on any Drupal site). I would *love* for you to come and help us hash this kind of stuff out because this is pretty much the task list for 2009. :-)

ooh, thanks for the fantastic reply! I would love to stop by the docs IRC meeting on Sunday--see you then :)