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.
As the Tracking Documentation Status page on LGO mentions, there are a few different ways writers can update a doc, including getting the relevant content in, but not updating all of the markup; writing the chapter headings to capture sections that need to be updated, but not adding the content yet; or working through the document step by step updating the content and markup.
I do the latter – I work sequentially through the document updating the markup and content. As I mentioned in Part II, I use Tomboy to capture my research on what updates the document needs, such as new features or bugs filed in Bugzilla.
Let’s start at the beginning of a document and work our way through it. I’m going to assume you’ll pickup the Docbook markup as you go, or have some familiararity with it. When I first started working on the Foresight User Guide a year and a half ago, I had no experience with it either. I would not claim I know it well at this point either – most of my experience comes from doing what we are about to do – just editing existing documentation, or at least using that as a base.
In Part II, you checked out the Tomboy source code out of GNOME Subversion. In your favorite text editor, open the Tomboy help file located in $/home/source/tomboy/help/C/tomboy.xml
Working through tomboy.xml section by section:
Description
<code markup="none"><abstract role="description"></abstract></code>
Find the above code snippet in tomboy.xml. This is the description of the project. Why is this important you may ask? Did you know that all of GNOME’s help files are also available online at http://library.gnome.org/users/ ?
If you click on that link and scroll down under “Utilities”, you will find Tomboy, and it’s description:
Tomboy Notes Manual
Tomboy is a simple desktop note-taking application, with some powerful built-in features to help you organise your ideas.
As part of Bug 500803, the above description needs to be updated, and this is the section where that change will be applied.
In the xml file, you will see:
<code markup="none"><abstract role="description">
<para>Tomboy is a simple desktop note-taking application, with some powerful built-in features to help you organise your ideas.
</para> </abstract>
Change the text inside the <para></para> tags to:
<br /> <abstract role=“description”> <para>Tomboy is a simple desktop note-taking application, with many features designed to help organize ideas, such as spell checking, highlighting, auto-linking URLs, lists, font stylizing, quick access with a table of contents for notes, and plug-ins to extend Tomboy’s capabilities. </para> </abstract><br />
Bug fixed!
Pulse Compatibility
Let’s make the Tomboy docs compatible with Pulse. As mentioned in Part I, familiarize yourself with the Status Tracking. Update the status by adding this block of code, as show in this example. This will add a status to the document, that Pulse can show, that lets other documentation writers know that the document is in the process of being updated, needs a review, or has been finalized.
Copyright & Author Information
Next, take credit for the work you’re doing – add your name to the copyright and author information. This is helpful to other doc writers as well, especially if you don’t have commit access, that other doc writers can reach out to you if they have a question with the last changes made. After the last tag, update with your name and year:
<code markup="none"><copyright><br />
<year>2009</year></p>
<p> <holder>Paul Cutler</holder><br /> </copyright>
Same under the <authorgroup> </authorgroup> tag, this time also including your email address:
<code markup="none"><author><br />
<firstname>Paul</firstname></p>
<p> <surname>Cutler</surname></p> <p> <affiliation><br /> <orgname>GNOME Documentation Project</orgname></p> <address><email>pcutler@foresightlinux.org</email></address> <p> </affiliation><br /> </author>
For the GNOME 2.26 cycle, I mostly added documentation to make the Tomoby docs reflect that it now works on both GNOME and Microsoft Windows. (Yes, I had to document an app to run on Windows! Who would have ever thought I’d be saying that…)
I’m not going to detail the markup of the changes I made; hopefully you’ll pickup Docbook’s syntax by editing changes inline in the document. (If you’re really curious, you can see the changes here in Bugzilla – the + denotes lines I added, and the – are lines I removed.) The above changes are changes you almost always want to make each time you update GNOME documentation.
As you document features for the application, think back to Part I, and revisit the GNOME Style Guide. Think about your audience, and focus on tone. Each documentation writer has their own strengths, whether that is tone, spelling, grammar, docbook markup, etc. Focus on your strengths and let the peer review process help you with the other areas.
Next is one of the most important parts – review your changes! Let’s fire up the xml file in Yelp, the GNOME Help Browser. To do this, Yelp has to call the file from the absolute path. For example, yelp tomboy.xml will not work.
yelp /home/yourusername/source/tomboy/help/C/tomboy.xml
And it should start. If Yelp starts, but doesn’t display anything, and an error pops up, close Yelp, and look at your console output. The console will tell you what line the syntax error is occurring that needs to be fixed. When I was first learning Docbook by writing the Foresight User Guide, I would spend twenty to thirty minutes trying to debug where I made an error. It can be frustrating, but you’ll find it.
Check your grammar, your tone, capitalization, and spelling. I will run two instances of Yelp side by side – the version I created / edited, and the actual help file for the application. (Run the application and hit F1 to bring up the help). I will compare the original against the changes I made.
When you’re comfortable with the changes, and Yelp displays everything correctly, it’s time to create a patch to submit those changes. You are probably like me and don’t have commit access to GNOME. Don’t worry though – keep working on GNOME docs and submitting patches and before you know it someone will recommend you be added.
As mentioned in Part II, the GNOME SVN wiki page has the details:
svn diff [filename] > [patch]
For Tomboy, I did:
svn diff tomboy.xml > docs-cross-platform.patch
I then updated Bug 576487 by choosing “Create a New Attachment” in Bugzilla, and filled out the form, noting the changes this patch made to tomboy.xml. I also let Sandy, one of the lead Tomboy developers, know in IRC that the patch was submitted and need a developer review and committed. You may also want to drop an email to the projects list to let them know the patch was submitted.
With that complete, it’s also recommended to have 3 peer reviews done by the GNOME Documentation team. I sent an email to the Docs list with a link to my bugs asking for peer reviews of my documentation changes.
As of this writing, I’m waiting to hear back from both my peers on the Docs team and Sandy on the Tomboy team. I’m sure there will be some changes that need to be made, as I’m nowhere close to knowing everything about how to write documentation, but I’m learning.
Once those changes are made, and the reviews are complete, the status will need to be changed to “candidate”. At that point, the GNOME Doc Team leaders will review it one more time, and with their approval, the document will be updated to “final” and committed! And you have officially helped to give back to the GNOME community and make GNOME better.
As I mentioned earlier, this may not be the best way for everyone, or the official way of doing things, but this is what works for me as I work on updating GNOME documentation. I hope you found this helpful, and feel free to leave me a comment below with your thoughts or questions.