Documentation From 6000 Miles

A lot of exciting things have been happening in the Gnome documenation world. One of the most exciting things to me is that much of the excitement is being driven by people other than me. For the last three weeks, my wife and I have been away on the Great American Road Trip. While we were gone, my team continued rocking. I’ve been pleasantly surprised to see people taking ownership, and absolutely delighted to see Mallard uptake.

Since I’ve been on the road, I haven’t had a chance to write much more than 140-character dents.  I need to  get back into the habit of writing daily, so I’m writing about the documentation-related topics that have rattled in my brain for the last 6000 miles.

(Note, if your aggregator strips images, you’re missing half the fun.  Clicky.)

Writing Open Source

Back in June, I attended the first ever Writing Open Source conference.  Thanks to some genorous help from the Gnome Foundation, four members of the Gnome documentation team were able to attend.  Meeting face-to-face in an atmosphere devoted to documentation allowed us to come together as a tightly knit team.  As I said, what’s exciting to me is that I’m not the only person driving things forward, and I really believe that’s due in large part to this event.

It wasn’t just Gnome folks, though.  We met people from various teams and shared our experiences and problems.  There is a lot we can learn from the greater open source documentation community, and a lot we can share with them.  The group has turned into a real community that is undertaking a number of shared initiatives.  If you’re interested in free software and free documentation, please get involved.

Thanks to the conference, I’m now in touch with Jim Campbell of the XFCE documentation team.  And through Jim, I’m in touch with Richard Johnson of the KDE documentation team.  I hope we can get some collaboration brewing.

Mallard

About four years ago, I got the idea in my head that we’re going about documenation in entirely the wrong way.  We write long user manuals that assume users will sit down and read.  That just doesn’t happen.  So I set about doing what any documentation tool developer would do: crafting a system to address the issues I’d encountered.

It took four long years, during which time words like “vaporware” started getting thrown around, but my experiences in those four years helped me turn Mallard from a hare-brained idea into something I believe is a viable documentation platform.  There is now experimental Mallard support in Yelp, and people are banging hard on it.

The feedback so far has been mostly positive, along with some valuable constructive criticism.  I’ve tried very hard to create a system that is easy for writers, translators, and distributors.  As an upstream project that often sees heavy modification by our distributors, we face some fairly unique challenges, and Mallard address some of those challenges in new and innovative ways.

CC

Gnome documentation has traditionally been licensed under the GFDL.  This was certainly a natural choice over a decade ago, but it’s become evident that the GFDL doesn’t suit our needs for various reasons.  This issue has been festering in our community for nearly as long as I have.

With the help of our own beloved almost-a-lawyer Luis Villa, our team has looked at our options and decided to use CC-BY-SA 3.0 for all future work.  Not only does the Creative Commons license suit the needs of our community better, it’s also being adopted by the Ubuntu and Fedora documentation teams, which can help foster collaboration between our communities.  Furthermore, it puts us smack in the middle of an amazing Free Culture movement.

Fun Ahead

There are far more exciting things happening in the Gnome documentation community than I have gimmicky road trip images for.  Paul, Phil, and Milo have been amazing in revitalizing our team.  If you’re interested in documentation, or if you’re looking for a way to get involved with Gnome, or if you just like road trip pictures, join us.  Subscribe to gnome-doc-list or point your IRC client to the #docs channel on irc.gnome.org.