Writing GNOME Docs, Part I
It’s been just over a year since I submitted my first patch to GNOME, for updated Tomboy documentation.
In that time, Shaun McCance of the GNOME Documentation team has been doing a lot of work to make it easier to get involved with the GNOME docs team.
Though Shaun is trying to make it easier to see which projects might need help with documentation updates, it’s still kind of overwhelming to try and figure out where to get started, especially as some of the information on the GNOME Docs team is outdated.
The Docs Team page on the GNOME wiki is a great place to start. Let’s take a look at a number of the steps it lays out, and I’ll try out point out where, in my opinion, some of the important steps lay and additional tools available, such as Pulse.
Step 1 & 2: Join the mailing list and IRC, as it refers to.
Step 3 & 4: Choose a project and document to work on. First, you should choose a project that interests you, and that you may know a little about. Here is a quote from Shaun McCance to the GNOME Docs mailing list on 5/8/08:
My general recommendation to new writers is to pick
an application manual for something you use frequently.
It’s easier to write documentation for an application
you’re familiar with. Smaller manuals will allow you
to go through the entire writing process and actually
finish something. Finishing things feels nice.
The good news is that this is one area Shaun is making easier with the Pulse project. Pulse isn’t officially released yet, and is run manually by Shaun. Pulse tracks all of the software in GNOME, including documentation and translations.
In January, Shaun sent an email to the GNOME Docs list that helps understand this process better, especially as it relates the GNOME 2.26 process, and with some updated steps that aren’t covered in the wiki:
When looking for documentation to work on, you can use Pulse to help sort:
Use Pulse to view all GNOME 2.26 documentation: [http://www.gnome.org/~shaunm/pulse/web/set/gnome-2-26-desktop#documents
]5
Pulse can show which docs don’t have a specific individual as a maintainer, and will display GDP (GNOME Documentation Project) if it doesn’t. It’s recommended to start with a document maintained by the GDP to work on. Follow this link: http://www.gnome.org/~shaunm/pulse/web/team/userdocs#documents and click on “Maintainer”. That shows the list of all projects maintained by the GDP. One of the advantages of working on a document maintained by the GDP is once your documentation move to the final state, the GNOME Docs team can commit the changes for you, as they are pre-approved with the maintainers of that project.
For my example though, wanting to update the Tomboy docs that I worked on a year ago, Tomboy is not maintained by the GDP. That’s ok – I’ve worked with one of the lead developers before, and I let him know in IRC that I was going to being working on documentation.
Going back to the Pulse list of documents, and clicking all, I then will choose and click on Tomboy.
Looking at the upper right hand corner of the Tomboy page in pulse, you will see:
Release Info
Status:
None
Familiarize yourself with the Status definitions that Pulse will display: http://live.gnome.org/DocumentationProject/StatusTracking
None – great! This is the document I’ll start working on as no one has started working on it yet.
Step 5: Going back to the GNOME Docs Wiki, step 5 is familiarizing yourself with the GNOME Style Guide.
The sections I found most useful, was Chapter 1, Fundamental Concepts, especially the sections on Tone and the Golden Rules. Chapter 7, Writing for GUIs, is good to cover as well.
When it comes to writing Docbook though, the best advice I can give is to jump in to a document – you’ll quickly learn the syntax with or without prior programming experience. I have zero programming experience outside of some very basic HTML , and by looking at a couple of different pieces of GNOME documentation, was able to write the Foresight User Guide in Docbook.
Steps 6 & 7: Create accounts in GNOME Bugzilla and the GNOME Wiki (aka live.gnome.org).
The only other advice I can give, especially as it relates to IRC and the mailing list, is to drop a note and introduce yourself, and let the community know you want to help out. All of this might sound complicated, but instead of spending hours wading through all of the documentation and webpages available (some of it really out of date), I think if you read the above steps it will start to make sense (at least it did for me!)
In Part 2, I’ll cover my experience in some of the basics around using SVN to check out a project, updating the status and the documentation, and submitting a patch.