GNOME Docs Team meeting tomorrow

What’s that? You follow but not For shame – we have a blog for the GNOME Documentation team but I guess this once I can cross-post for you.

We’re having a meeting tomorrow at 19:00 UTC in #docs on to start planning the topics and task for GNOME 3.0. We have big things (like GNOME Shell) to document and lots of little topics to tackle as we break up the old GNOME User Guide and organize it better.

As the post on the Docs blog says – now is a great time to get involved – even if you don’t know Docbook or Mallard, the important thing is to write the new user help and we’re here to help you learn.

See you there!

Docs Team Meetings

The Docs team is having two meetings in the next week – a community Q&A session tomorrow, and a project meeting this Sunday. More details on our shiny new blog at (Thanks Olav for adding us to!)

Speaking of our shiny new blog, does anyone know how to add additional authors to a blog on I haven’t been able to figure it out and I’d like to add Shaun. Is it a setting that’s right under my nose and I just don’t see it? Thanks!

GNOME Docs Hackfest Part II

Day three of the Writing Open Source conference was our hackfest. I previously showed off Milo’s work in Part I, but it’s probably best to start at the beginning.

We started day three by applying some of what we had learned over the first two days. When writing, especially documentation, it is best to plan your work. This includes knowing your audience, their personas, and understanding their needs.

Lynda Chiotti, with help from Janet Swisher, led us through a brainstorming exercise. Using a mind mapping tool, we brainstormed what users want to do (and might need help with) when using their computer.

This was important for a few different reasons. For GNOME 3.0, we want to re-write the GNOME User Guide as topic based help using Mallard. Re-creating might be a better word, as we are going to switch licenses from the GFDL to CC-SA 3.0, and it’s probably easier to re-write it from scratch than to contact all the previous authors over the years to get permission. More importantly, we need to think like our users. How many times do we, as GNOME power users and developers, talk to ourselves, and not think like the average computer user? If this user needs help, does our documentation help them? Do they get frustrated and stop using GNOME or GNOME applications? We have a unique opportunity to use both our tools and the launch of GNOME 3.0 to radically improve our documentation and help our users.

After that, Phil, Milo, Shaun and I spent some time talking about how we could improve the GNOME Documentation Project. There were no sacred cows, and we’ve launched an effort to overhaul the docs team, including:

  • Adding simple tasks that new contributors can do and then build on (thanks Emma!)
  • Focusing the docs team on writers, editors, and translators. Each perform different, but similar roles, including crossover. We need to improve our tools for each team, and communication.
  • Holding more regular meetings, including a monthly project meeting, and weekly community sessions to encourage participation
  • Developing a roadmap of tasks we want to accomplish, including both the documentation itself and the tools
  • Understanding Shaun’s role as our fearless documentation project leader, and how we can help him to free him up and not having the team be blocked on any one person.
  • Make a significant effort to coordinate with downstream distributions, including meetings and communication, introducing Mallard, and better comments within documentation.

And that’s just the recap! Our wiki space is going through a revamp as we bring this to life, and there is a lot more to come.

Lastly, while Phil and Milo started hacking on Empathy docs using Mallard, I jumped into Bugzilla. Almost half of our open bugs in gnome-user-docs were touched (36 of 80), and of those 36, 23 were closed. Finally, 16 commits were made to update the current User Guide, including reviewing and patches from contributors. Fun fact (or embarrassing) – the oldest bug fixed was from July, 2006.

Overall, woscon was an amazing experience, and we all learned a lot. A few years from now, we’ll be able to look back and say: “We were there when this began”.

I think I speak for all of the GNOME Docs team members who were there, including Phil, Milo, and Shaun when I say we are sincerely thankful for the GNOME Foundation’s sponsorship of our travel to the Writing Open Source conference. This conference was the brain child of Emma Jane Hogbin, and we are very grateful for all the time and effort she put in to organizing and hosting woscon.

GNOME Docs Hackfest (Part I)


(A duck at Inglis Falls, in Owen Sound, Ontario, home of woscon09. If only it had been a mallard…)

Milo Casagrande, who attended woscon09 with the GNOME Docs team last week, has written an introduction to Mallard.

Milo and Phil spent Sunday’s hackfest creating the first Mallard document for use as a help file within an application. We chose Empathy, for a few different reasons, including: it will be in GNOME in 2.28; the current documentation is not completed; we want to re-license it from GFDL to CC BY-SA 3.0 and Milo and one other collaborator were the only ones who had worked on it previously (though we fulfill our obligations in re-licensing by the exercise below).

Using the information we learned Friday and Saturday, we spent time planning the document and brainstorming what users want a messaging application to do, and what questions they might have: “How do I….?”.

From there, and with great gusto, Phil and Milo spent the sprint creating a proof of concept help file for Empathy. Not only is it written in Mallard, which can dynamically link the pages, we are focusing on creating topic based help, rather than tasks that take a user step by step in performing an action. Phil and Milo will probably have words with me, but you can follow along on the empathy-mallard branch in Gitorious.

You will need Yelp 2.27.1 and gnome-doc-utils 0.17.1 to see a Mallard doc in Yelp. And now I have to go figure out why Yelp isn’t cooperating with me.

Docs Team & Community


(The Ginger Press Cafe where the work, talk and laughter happened at woscon09)

One of the most important take-aways for me personally from woscon09 were the talks on community. This included Addy’s keynote Friday on herding cats, the challenges that spanned all of our groups, discussion around upstream to downstream and back again, and encouraging new volunteers.

With that in mind, we’re making some changes to the Docs team to improve our community involvement.

Last night, Shaun sent an email to the list detailing some of the changes, including:

  • Community Management
  • Editorial assistance
  • Reviews
  • Upstreaming downstream

And, of course, we are all responsible for writing.

With that said, I’ve spent some time over the last day or two re-organizing our wiki, and have put together a stub of a page around Community.

We will be having our first Q&A session this week, starting tomorrow night at 9 p.m. CST (2:00 a.m. UTC). We are committed to having these meetings, and moving the day and times around to get as much representation worldwide as we can.

The theme of tomorrow’s meeting is a recap of what we learned at woscon09. However, please bring any questions. Want to know how to get involved? What to write? How to use bugzilla? This is an open session, and more than anything, it’s to let folks know that we will be in IRC at a given time to answer any question (within reason). Stop by #docs on GIMPnet IRC tomorrow night!

We’ve also started a Docs Team blog where we will be posting meeting announcements, recaps, and other important information that we wish to share with the community.

Have you ever wanted to help out? Feel you can write technical documentation? Have above average grammar and spelling and want to edit? Translate our docs? Now is the time to get involved. We have lots of exciting things planned for this year, and this is just the tip of the iceberg.