docs

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.

GNOME Odds & Ends

A few different things going on: Tomboy documentation is almost done in Mallard. I’ve really enjoyed using the Mallard syntax – so much less complex than Docbook. Every time I have to look up an element reference, I shake my head and think, “Duh! That makes so much more sense I should have figured that out!“. Nice work Shaun. I triaged some docs bugs in GNOME Bugzilla. Want to get involved with the GNOME Documentation team but don’t know where to start?

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.

Writing Open Source

The first ever (that we know of) conference for documentation writers in open source conference started today in Owen Sound, Ontario (about 2 hours from Toronto). The Writing Open Source conference is being hosted by Emma Jane Hogbin, and a few of us from GNOME are here:

(Left to Right: Shaun McCance, Milo Cassagrande, Phil Bull and myself). We’re halfway through the first day, which is keynotes, and the conference is awesome.

GNOME Updates

Lots of stuff going on in the world of GNOME for me! Attended a few meetings last week with GNOME related projects. This past Sunday, April 19th, the Documentation team met for the first time in a while. Shaun gave an update on the status of Mallard, the new markup language for GNOME Docs; a possible change to how we license docs; an introduction to Pulse and some brainstorming on new ways to bring guides to users.

GNOME Documentation Meeting

There is a GNOME Documentation Team meeting this Sunday, at 17:00 UTC. I am a sucker volunteered to help Shaun McCance facilitate the meeting. Here is the meeting announcement I just sent to the mailing list: Are you a seasoned and wily Docbook veteran? New to writing documentation and don’t know where to start? Now is a great time to join the team! There is not a formal agenda, but we will start with Shaun giving a brief update on Project Mallard (http://live.

Writing GNOME Docs, Part III (Let's write some code!)

I’ve been chronicling my learning on writing documentation for GNOME. In Part I, I covered getting up to speed on GNOME documentation and the tools available; and in Part II I wrote about picking a project that you want to help, getting involved, and setting up your environment and finding updates that need to be made. Now it’s time to apply those needed updates to the documentation and write some actual code in Docbook.

Writing GNOME Docs, Part II

So you’ve decided you want to contribute to GNOME and write some documentation. In Part I, I wrote about the steps I went through to prepare to write GNOME documentation and picking a project. In Part II, we will take a look at the final preparation stage, including checking out the project’s source code via GNOME Subversion and finding documentation that needs updating. I am still fairly new to the process myself, but these are some of the steps I take in writing documentation.