in Documentation

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.

  1. I wonder what kind of results the following would produce: 3 or 4 non-linux users given some minor compensation (Amazon MT perhaps) to spend a few hours on the system “blind,” figure out how to do a task, and produce a rough draft of “how to burn a CD” and then have doc folks combine the best of the submissions and then re-edit/re-write it into a final.

  2. Rob, that’s a really interesting idea. Though I think I’d downgrade our expectations from “rough draft” to “brain dump”. I wouldn’t want them to focus on cleaning up the language at all. Just give a basic step-by-step, and if you have any questions or WTFs, just leave those right in the write-up.

Comments are closed.