Documentation

Why I enjoy writing user help for GNOME

It’s been almost ten years since I started contributing to open source projects. One of the big ways I’ve contributed in the past is writing user help. Not knowing how to code then (and still really don’t know now, as hard as I try to learn Python), writing is something I enjoy and an area where I think I can make a difference. There are a number of different places to apply a writing skill in open source.

GNOME Docs Team meeting tomorrow

What’s that? You follow planet.gnome.org but not news.gnome.org? 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 irc.gimp.org 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.

Quack – An update on GNOME 3.0 Help

One of the big improvements for GNOME 3.0 is new user help. The Documentation Team is using Mallard to re-write the GNOME User Guide and a number of applications help files as well. In GNOME today, most help files are written in a very linear structure by chapter using Docbook XML. If you’re a user looking for help, it’s not always easy to find the right chapter that contains the topic you’re looking for help with.

Plan your writing

I’ve been meaning to follow-up on Shaun’s recent bog post about “Explain More” when writing user help. Zonker’s blog post this morning on how to write an interview finally motivated me to get this blog post done. One of my favorite sayings in a work environment is “Plan the work and work the plan”. This applies to writing as well. One of the two major takeaways I had last year after attending the first Writing Open Source conference was the importance of planning.

Banshee Documentation

I’ve been working on Banshee documentation on and off for the last few months (ok, more off than on) but as I get more comfortable writing in Mallard and the recent discussion in getting Banshee on the GNOME release cycle I am motivated to get this to done. The most important part of writing documentation (or writing in general) is the planning phase. A few of us on the Docs team did a first pass at planning the topics that should be in the user help of Banshee in Google Wave, and I’ve copied that over to the GNOME wiki.

Google Wave

Almost two months ago, Nigel Tao posted on his blog offering Google Wave invites to the GNOME community. I commented and requested some invites for the Documentation Team, with Nigel graciously granting the request, and he asked for some feedback after using Wave for the last month and a half or so. Some of the feedback that I shared with him, in no particular order: We in the Docs team have used Wave to do document planning.

Mallard Documentation

Did anyone watch The Office last Thursday night? Early in the episode, Dwight gives Jim a wood duck with a walkie-talkie built-in so Dwight can spy on Jim. Jim: Thanks for the duck Dwight: It’s not a duck, it’s a mallard! This had me chuckling thinking about Mallard documentation. For the record, mallards are a much more beautiful duck than wood ducks. There’s been a lot going on in the world of GNOME documentation.

Gran Canaria Part II

I continue to have a great time here at the Gran Canaria Desktop Summit. I keep putting off blogging as I’m just overwhelmed with everything going through my head, and trying to make a succinct blog post has been a challenge. One of the best parts, especially as it’s my first GUADEC, is how welcoming everyone is. I think I’ve had lunch or dinner with a different group of people every meal.

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 http://blogs.gnome.org/docs/2009/06/24/upcoming-documentation-june-meetings/ (Thanks Olav for adding us to news.gnome.org!) Speaking of our shiny new blog, does anyone know how to add additional authors to a blog on blogs.gnome.org? I haven’t been able to figure it out and I’d like to add Shaun.

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.