Issue #19 May 2006

Better Linux release notes through design thinking


One of the lessons we've learned in the Fedora™ Documentation Project is that open source methodologies are not just for software coders and hardy beta testers. It is only one small step to apply the same collaboration methods to open source documentation, but it is a step that shows a new and powerful path.

When Fedora Documentation became functionally separated from the documentation team working on Red Hat® Enterprise Linux®, one of the writing functions we lost was for the release notes. Out of all the documents that a software project could write, release notes are the one that should be written.

We knocked around a number of plans. A document the size and scope of a release notes is a stretch for a single writer to tackle full-time. Trying to do this in the community with one or even three writers is simply too much to ask or expect. To be succesful, we needed to apply principals of open source development. Modularize. Reduce content needs to chunks that a volunteer writer can handle. Focus discrete chunks onto areas of interest that can attract a contributor.

From this was born a simple but powerful concept -- the release notes beat.

In journalism, a beat is an area of coverage that one or a few writers focus on. It might be politics in the local government, football with the local league, sports in general, fashion, food, and so forth. A beat writer has a chance to get to know an area as a specialist, to become a face and name known by the newsmakers being covered in the beat.

To cover Fedora Core release notes, we divide into different beats that cover areas such as the kernel, security, desktop, installation, and so forth. Each beat has one or more writers, who either come from an appropriate project or enter as an interested contributor who wants to get closer to the technology and the programmers.

For the programmers, there is now a single person whose job it is to tell their story. The programmers know who to send content to, and can help the beat writer become an integral part and one of the voices of the sub-project.

Once we had this basic idea in front of us, the tools and processes became obvious.

First, we knew that we had to take contributions via the Wiki. For this, we created the permanent release notes draft space at http://fedoraproject.org/wiki/Docs/Beats. At anytime during the development and release cycles, beat writers and other project contributors come to these Wiki pages to make notes that become part of the release notes.

We used another technique from open source development, the commits mailing list. This is a list that receives email of all the changes made to the software as it is committed into the code repository. By watching this mailing list, developers and other watchers can learn from each other, correct mistakes as they are committed, begin discussions based on the direction the code is taking, and so forth. We applied this same technique to the beat writing.

As each change to Docs/Beats is committed, a team of editors and fellow writers are watching the commit. We can step in and immediately edit content, fixing typos, grammar, and style issues while the content is fresh. Combined with IRC and email, editors provide real time, global, 24-hour assistance to beat writers.

Early in the process, we realized that we needed to settle on a Wiki markup style. Writers were using whatever appealed to them, what they picked up recently, or what was in use in the section they were working on. By having a style and using it consistently, contributors watch and correct each other. Rather than going through an extensive training program, writers are invited to begin contributing and learn as they go. When writers makes a style mistake, they often see their content fixed and updated within the hour, and the commit message for that change has a link back to the style guidelines as a gentle reminder.

Fedora Documentation also produces release notes to go with each test release of Fedora Core. This means we need to gather and output release notes for at least three tests and one final release. This includes a Web-based version of the release notes that incorporates last minute content changes from the Wiki, which is produced and published in the 36 hours before Fedora Core test or final release.

There is another reason we do a last minute, Web-only publishing of the release notes. Because we freeze changes to the release notes in the ISO around nine days before the ISO is spun (created), we want to provide another snapshot of the latest, freshest content. The reason for this freeze is to include translations of the release notes in the ISO. To do this we follow a strict schedule that freezes content in the Wiki while we output to DocBook XML. This XML is cleaned up from the conversion, then made available in CVS for translators. The original English and all translations are then gathered and included in the fedora-release package.

For each test release and final release of Fedora Core 5, we had multiple languages available: Brazilian Portuguese, English, Italian, Japanese, Punjabi, Russian, and Simplified Chinese.

While this is happening, the Wiki is unfrozen and content continues to be included, and these final changes are part of the Web-only publication. The older process of filing bug reports for release notes is now supplemented or replaced with allowing all Fedora contributors to add to and fix the release notes directly via the Wiki.

You can see from the colophon that more than 20 people contributed directly to the release notes for Fedora Core 5. These people gathered content while involved in their communities, and in many cases were the conduit for content and suggestions from other people. Just like programmers are the gateway for patches from the community, beat writers are the gateway for content from many sources into one set of release notes.

Because the release notes are the default homepage in Firefox in a base Fedora Core install, we have focused on making them more attractive and relevant. In years past, this default page was the beginning of the legal boilerplate. Now, you are greeted with a tip to visit the latest version of the release notes on the Web, then a Table of Contents with a prominent release overview.

No login required. Want to see your comments in print? Send a letter to the editor.

What follows that is 45 printed HTML pages of the best release notes of any Linux distribution.

If you like this idea, wait until you see how we are going to apply the beat concept to all the documentation. Stay tuned.

About the author

Karsten Wade is the leader of the Fedora Documentation Project and a senior developer relations manager at Red Hat. Formerly a services consultant and Engineering technical writer, Karsten is now focused on bringing corporate developers the Red Hat world of content, community, and collaboration found in the best practices of free/libre and open source software.