docs

Professional cat herder = win

Cindy, cat herderIn my post last week I mentioned that we had a professional cat herder, Cindy McCourt, for the Toronto Drupal documentation sprint and that the entire approach was a bit new and different for us. It was certainly different than anything I'd done before, especially in the Open Source or Drupal world. I should start by noting that all of this grew from community efforts by a number of people and isn't any kind of brainchild of mine. This sprint was an awesome showing of how Drupal contributors can do amazing things.

Writing Open Source Conference

Doing documentation in open source is often hard, doing it well is even harder. All projects have to struggle with this in some way and, in true open source community spirit, why don't we get together and help each other? I'm excited to spread the word that the open source world is going to get its very own documentation conference. I've been in on a new conference/unconference/sprint being planned for this June up in the great province of Ontario, Canada, called Writing Open Source. The idea was born last fall between a few conversations that Emma Jane Hogbin had with myself and Belinda Lopez. Emma was all crazy-talking about a whole conference just focusing on documentation and I couldn't resist such an awesome idea. Then the talking turned into planning, we got a space (in a library, no less!), some totally awesomely delicious catering, a domain name and now registration is open!

Docs Challenge March: Style guide review

I know I'm a bit late on the monthly challenge this time around, but between the Usability sprint and Drupalcon I've been a bit too hectic to get a post written up. So this will be a short month, but hopefully we can rock it anyway. This month the focus will be on spiffing up our handbook by reviewing what we have and applying the style guide to it. Much like how the coding standards make working with Drupal code a lot nicer (especially for newbies), having consistency and clarity in our handbooks will make it easier for people to understand the firehose of information on any given page. I found that the best way for me to learn Drupal coding standards was to review existing code and help fix it. This month's task should not only help us clean up the docs a bit, but also get more people familiar with the fact that we even have guidelines as well as tucking some things into the back of their minds for next time they write or edit.

Funding for Drupal docs gets real

At the Drupalcon DC keynote I was in for a bit of a shock. After Dries had delivered the State of Drupal and its general rockingness, Jose Zamora from the Knight Foundation took the stage. He started talking about the Drupal proposals that were submitted last year to the Knight Drupal Initiative (KDI), one of which was mine, for doing Drupal documentation sprints. I had been informed that the board meeting necessary for the decision about which proposals would win funding wouldn't happen until next week so I figured he would just talk about it to spread the word about Knight. Well, turns out he had a surprise: he had confirmed the winners and I was one of them. The Knight Foundation has awarded me $50,500 to make Drupal docs kick ass this year.

For a quick summary, the money will be spent to cover three basic things:

    Sprinting isn't just for code

    A grand tradition of Drupalcons is to end with a day of sprinting. Sprints are most often associated with a bunch of hackers chewing on code. Well, our community is more than code or coders. We are a rich community both in people and in the broader work we do to keep Drupal-land humming smoothly along. At this Drupalcon, like the last two, we'll be having an all-day documentation sprint on the last day, March 7. This year we will be a bit more organized and we have a whole room set aside just for us. And just who is "us?" This year a big goal of mine is to really get the word out that everyone can help with docs. We need people from all skill sets, backgrounds and languages; newbie to code ninja. Documentation work is not just about writing. Even taking one hour to hop in to help will push Drupal forward in leaps and bounds.

    Help the Drupal Help system, help you

    Aside from general docs work, like the monthly challenges and our current projects, my main priority the last few weeks (and into the foreseeable future) is getting a new Help system into Drupal 7 and making it kick behind. The patch to get the base system in is very close and we just need a bit more work to tip it over. Drupal 7 is aiming to be one incredible release and it is now time to really focus hard on things to make it useful to mere mortals: usability and documentation. If you care at all about the everyman in the CMS drama, then it's time to put on yer grown-up pants and get to work.

    What needs to be done right now

    Currently what we really need are reviews and feedback. Here are the major pieces we need eyes on:

      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.

      Docs Challenge January: tending the queue

      With the start of the new year, I've decided I'm going to run a monthly "Docs Challenge." I've got another post coming down the pike that lays out my long-term goals and the big pieces of the Drupal docs puzzle for this year. One of those goals is to find ways to make contributing to documentation clearer and easier. By setting up monthly challenges, I want to outline and give guidance on docs tasks throughout the year. It is one thing to tell people they can help and give them the tools, and quite another to actually explain what that means and guide them through the process. These challenges will hopefully not only get needed documentation tasks done, but show everyone exactly what it all means and that they really, really can help out. So, without further ado, my Docs Challenge for January is to clean up the docs issue queue on Drupal.org. We currently have about 200 issues covering 4 pages. I'd like to get that down to 150 (3 pages) by the end of the month. To that end, I'm going to set aside at least one hour each weekend day in January, from 1-2 p.m. EST (18:00-19:00 GMT) to work on the queue. I'll spend that hour on IRC in #drupal-docs on Freenode to answer questions and teach anyone who wants to learn as well. Fifty issues is a lot to get through and I'm going to need at least a little bit of help.

      Pages

      Subscribe to docs