Blog - PaulCutler.org

March 26, 2009
in GNOME, Linux
4 min read

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.

Part III will cover updating the Docbook XML file, reviewing your changes and submitting a patch with the updated docs.

Now that you’ve picked a project to work on, I recommend subscribing to the project’s mailing list, and, if they have one, hang out in their IRC channel. A list of all GNOME mailing lists is here, and be aware of the GNOME Code of Conduct when sending an email to a list.

Personally, I recommend letting the project or lead developer(s) know you want to help out. This is helpful for a couple of reasons, including:

If you, like me, are new to contributing to GNOME, you probably don’t have SVN access to commit your changes. A developer on the project, or a member of the GDP if you’re working on a project the GDP can commit, will have to submit your changes to the project.
You might have a question on how a feature works, and want clarification. If you’ve introduced yourself, other project members will understand why you’re asking.
Help is always appreciated! You have nothing to worry about – almost all projects will welcome you with open arms. Especially doc writers, as it sometimes considered unglamorous work.

As I mentioned in Part I, I’ll be working on the Tomboy documentation, and I sent an email to the list letting the developers know, and asking if there were any areas of the docs that also needed changes or updates. (The Tomboy mailing list is generating a 404 error when I try and click on my email which can be found here).

In a terminal, create a directory where you will to checkout the source code of the project too. GNOME uses Subversion, and will be moving to git in the future. The GNOME Wiki has a great page on using Subversion. Move to the directory where you want the source code, and per the GNOME SVN wiki page, checkout the project:

svn co http://svn.gnome.org/svn/[module]/trunk [module]

For Tomboy, I would do:

<br /> svn co http://svn.gnome.org/svn/tomboy/trunk tomboy

The Tomboy source code is now checked out to the “tomboy” directory in the directory I’m currently in. For the purpose of this example, we will assume you checked out the source code to $/home/source/tomboy

Now it’s time to find some documentation that needs updating. Good sources to find documentation updates include:

Projects’s Bugzilla
Reviewing the projects current documentation
Project’s release announcement of new features
Mailing list

I recommend starting by doing a query in the project’s Bugzilla (bug tracker) and see if any users have filed bugs or requests against the project’s existing documentation.

Log in to GNOME Bugzilla, and click the “Browse” button in the top menu. On the Browse page, click on the drop down menu next to “Browse:” and click on the project you want to view, and “Show product”. You will be taken to the project’s Bugzilla page, which provides an overview of the number of bugs, type, and severity, among other information.

In the search box towards the top, you will see “project:Tomboy” already entered (or the project you chose), after that type documentation and hit search. The results will show any bugs that have a keyword of documentation, and you can browse through any open bugs to see if there are any changes that need to be added to the project’s documentation.

You will want to keep notes of any bugs you come across, or changes and updates the documentation file needs. Ironically, Tomboy is a great tool for this, and even supports the ability to drag and drop a GNOME Bugzilla link from your browser into Tomboy and converts it to an easy to use link.

I also recommend reviewing the project’s current documentation. Open the application, and hit F1 to bring up the help in the GNOME Help Browser (Yelp). With GNOME being on a 6 month release cycle, it may be possible that new features were added without being documented, which is why it’s also helpful to see if there was a Release announcement that outlines those new features.

Review the sections in the documentation, and compare to the behavior of the application. Do they match? If not, it might be useful to ask the developers in IRC or on the mailing list to double check, and make a note that the documentation needs to be updated to reflect those changes. This process can be time intensive, which is why you may want to start working on documentation with an application you’ve used and are familiar with.

If you introduced yourself on the project’s mailing list, the community members may have pointed out some areas that need updates as well.

Hopefully this has helped in getting you ready to (finally!) update the documentation. In Part III, I’ll cover updating the documentation’s Docboox / XML file and submitting your changes to the project.

March 25, 2009
in GNOME, Linux
4 min read

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.

March 24, 2009
in Foresight
1 min read

Foresight Website

It’s been just over a year since we rolled out the new Foresight website, which is written in HTML.

After some on and off debate, we’ve made the decision to switch to a CMS (which makes it much easier to get volunteers involved), and as of last night we’ve picked Joomla over Drupal.

We’ve set up our appliance on rBuilder, and we’re looking for help in building and maintaining the appliance, and even more important in designing a Joomla template for the look and feel of the new Foresightlinux.org. A big thanks goes out to pscott, Lance Haig and Tomas Forsman for getting us this far.

Join the marketing list and give us a hand today!