Documentation Team Meeting

The Gnome documentation team will hold a team meeting this Sunday the 10th at 18:00 UTC. We will discuss Mallard page templates, the accessibility documentation, and plans for, plus anything else that people want to discuss.  Feel free to add to the agenda on the wiki.

Please plan to attend, whether you’re an experienced documentation person or not.  The documentation team is a great way to get involved with Gnome, and we have a lot of exciting things happening right now.

(Copied from the documentation team blog.)

Documentation at the Summit

I’m hoping to lead two sessions about documentation at the Boston Summit this year.  Hopefully I can garner some interest from the blogosphere.

First, I want to give a short talk on topic-oriented documentation.  This is a very different way of thinking about your documentation, and I’d like to introduce people to it and convey some best practices.  The documentation team went topic-oriented with the new Mallard-based Empathy Help this release cycle.  But topic-oriented isn’t limited to Mallard, nor is it only relevant to user help.  I’ll try to keep the concepts general, while still giving guidance for the real-world systems we use.

After that, I’d like to have about three hours to lead a docfest.  I will help you write or improve any piece of documentation you bring to me.  If you don’t have something in mind already, I’ll find something for you.  It does not have to be user help, and it does not have to be topic-oriented.  I realize this is a hacker’s event, so bring me your API references or developer tutorials.  We’ll turn it from a random collection of thoughts into a coherent document people enjoy reading.

If you’re interested in either, please leave a comment.  Or send me an email at shaunm at gnome dot org.

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.



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.



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

Creative Commons Attribution 3.0 United States
This work by Shaun McCance is licensed under a Creative Commons Attribution 3.0 United States.