How to be a release notes beat writer

There is plenty of information on the wiki about how to become a beat writer. We need people who will pick up a piece that interests them and help tell the world. What is lacking is help in how to execute the duties of a beat writer. This page hopes to address that. Please take care to note that these are the opinions of one beat writer, and perhaps something of an outlier at that.

The Process
During the release cycle, there are things that need to be done to stay on top of the release. Most of these, honestly, are pretty lightweight. They may seem a bit daunting at first, but really, they're not too bad. The hardest part, though, is understanding what is expected; this page hopes to address that.

Finding out what a Beat looks like
The beat page in the wiki ultimately becomes a section of the release notes for the next release of Fedora. It's primary objective is to help people understand what has changed. Depending on the beat, it might be helpful to begin with a 'short' synopsis of what is in the beat, but the main thrust should be to describe the changes between the next release and the previous.

Just how detailed this should be depends on the particular topic. For many packages a simple note mentioning a new version of a particular package, perhaps with a short description of new features is adequate. For a completely new package, you may want to be a little more detailed. Most packages come from an upstream project, so in general you want to include a link to the upstream's release notes.

Sometimes a package has changed in a way that requires action from a user. Perhaps the user must install an external package, perhaps (s)he must do some sort of file conversion. When this happens, the beat must include at least a warning, and a link to the details. In cases where there are probably many users, and especially when those users might be less experienced, then a detailed, step-by-step description of what needs to be done is in order.

Read through the current version of the release notes. You will see examples of both very brief descriptions and very detailed descriptions. As you read through the release notes, keep in mind that the audience for, say, gcc is a very different audience than that for the Flash plugin, for example, even though they end up in the same document.

Finding out what is in the Beat
This sounds simple, but is probably the hardest part. You took on (or are thinking of taking on) the Beat Writer duties because there is a subject within Fedora that you care about, and maybe are even familiar with. You probably already use some of the packages in your particular beat. The operative word there is some. Fedora now has well over 11,000 packages. Chances are there are packages in your area you don't know about. The good news is that you are likely to find packages you wish you knew about sooner!

PackageKit is one obvious place to start. PackageKit is not organized by Beats. As a result, not all packages are in obvious places in PackageKit, and many packages "belong" in multiple groups. But at least PackageKit is a start. The GUI for PackageKit wasn't really aimed at Beat Writers, so this process can be a little tedious.

When you are looking around in PackageKit, at least scan groups that don't seem to be related to your beat. The people who organized the groups in PackageKit had a different point of view. Even when a package at first seems way out of bounds for a particular group, usually if you give it a little thought, you can see the rationale, even though you may not agree with it.

A somewhat faster, but less friendly, way of searching the groups is to issue a  command, find some groups that look relevant, and then do a   to see a list of packages in the group. For packages that you aren't familiar with, you may still need to do a  on the package. With PackageKit you can simply select the package name to see the same description.

If your particular area of interest is supported by a SIG, then the SIG's page on the wiki is probably the best place to look. The SIG page not only has the current packages, but often has news of planned packages. Unfortunately, not all beats are supported by SIGs.

Finding out what has changed
The largest part of the job is keeping track of what has changed so that you can report on it for the release notes. The "company line" as it were is to stay in contact with developers and watch commits. Well, there are a couple of problems with that. If you can hook up with a developer that is obviously the optimum. Often, though, it isn't obvious who the developer is, and developers often have little interest in documentation, and even when they do, a developer's view of the world is quite a bit different than a user. The developer will often tend to be really excited about some change that is invisible to the end user, while ignoring significant new features. Still, maintaining a dialog with the developer is definitely the best approach.

Watching commits isn't a bad plan in theory, there is even an RSS feed. The problem is that with 11,000+ packages, there are a lot of commits. It isn't always all that easy to pick out the commits that you care about from the dozens or hundreds every day.

Probably the almost perfect situation again is if your beat has a SIG. The SIG page will probably link to a table listing packages and work being done on them. This is an ideal way to keep up with what is happening in your beat. The problem of course is the same as for identifying the packages in the first place; only a few beats have corresponding SIGs.

Probably the easiest, if a little tedious, is to look at the repositories. If you have a list of packages in your beat, you can make note of the versions for the previous release. Then from time to time you can look at the rawhide repositories for each of your packages and see what the current rawhide version is.

A variant on looking through the repository is to look in the yum database. Each repository has a  file that lists all the files in the repo and their versions. This is a SQL database and the  program provides a text interface to the database. If you are comfortable with SQL, this is a much quicker approach than going through the rather long web page that describes the repository. There is a hack (tar here) that attempts to make that a little easier.

Dale Bewley has a script for examining the koji files to see changes. He describes it here.

Once you know what package has changed, you now need to find out what has changed. Again, if your beat has a SIG or you are in contact with the developer, this is already pretty obvious to you. But if you are operating a little more at arms length it is a little less obvious. Again, the yum database comes to the rescue. If you issue the command, yum will cough up a short description of the package, along with the URL of the package's project. Almost always that URL will lead you to the release notes for the upstream package.

Sometimes the upstream has weak or no release notes. Some insight into what has been done can be gleaned by looking at the change log in the RPM. If you have downloaded a copy of the RPM or have the package installed you can issue a  command and see the list of commits. The comments will give you a view into what has been happening with the package.

Depending on your capabilities and the resources available to you, it might be appropriate to install the rawhide package and explore it so you can write authoritatively.

The wiki
The primary method for providing release notes content is this wiki. The wiki is relatively easy to use, and since MediaWiki is a widely used wiki, it is well documented. There are a few Fedora unique styles and templates, these are described in the editing help page.

The main benefit of the wiki is that it allows so many people to contribute. You aren't likely to be familiar with all the packages in your beat, but those people who are likely to read your wiki page are exactly those people who are likely to be familiar with the packages. This allows you to pick up on a lot of details of some of the packages that may otherwise elude you.

Publican
The release notes are produced by a package called Publican, and you must have the latest version of Publican installed if you want to build the release notes. The good news is that there isn't a lot about Publican that you need to know. Publican basically creates an empty DocBook document. By the time you, as a beat writer, need to work with that tool, the Publican part is done.

Basically, Publican is a big, lumbering package and the release notes are produced in a zillion languages (well, OK, I count only 40). This means that should you inadvertently try to build all the languages, it will take a very long time. Once you have the release notes cloned from git, you can make just the U.S. English version by:

The process of cloning the common tools and release notes from the git repository is described elsewhere.

DocBook
As the time for release closes in, you may need to make last-minute changes in DocBook. You may also find that updates will need to be made in DocBook from time to time. Fortunately, like Publican, you really don't need to know a lot about DocBook to use it.

The source for the release notes is consists of a number (roughly a couple dozen) XML files. These files can be edited with a normal text editor, although it may be a little easier to use an editor that understands XML like emacs. Since there is generally not a lot of formatting to be done anyway, and especially in the sorts of edits that are likely to be applied to XML, it is fairly simple to look at other parts of the document for guidance on how to make your changes.

Once you have changed the XML, you can rebuild the release notes with  as above, to see what the final result will look like. Be sure to carefully review the changes in the final form before committing them back to git.

Random Release Notes Philosophy
The Fedora Core release notes (relnotes) are a massive undertaking for a single individual to do manually. Even as a group effort, the collection and sorting for useful bits of information (content) to document is a large undertaking.

For the release notes and all documentation to be meaningful and useful, the developers need to embrace them as part of their process.

Process additions for developers need to minimally interrupt an already working and complex workflow.

Places in the workflow we can capture useful content to document include:

1. CVS check-in comments 1. bugzilla for all packages 1. easy-to-send-to email address

The Pieces of the Relnotes Process
There are two major parts: the in-flow of content from developers and the community, and the churning of that content into a release notes. We'll call them the gathering and writing parts.

Gathering the content
For CVS check-in, we use unique keywords in the commit log. The current usage is, and that is can be added to in the future to control many server-side behaviors. The log message should include a longer description explaining the change. Similar for changes to packages overall. To do this, we worked with release engineering (rel-eng) to automate the extraction of that content.

Beat writers (doc teams) can then work on the content throughout the development process. As the directed commit log comes in, beat writers scan it and direct it to the most appropriate person. That beat writer does one of the following:

1. Discards it as irrelevant or otherwise covered 2. Immediately adds the content into the beats, such as through the Wiki 3. Sends private or mailing list email to get further information or explanation 4. Files a bugzilla with a block against a tracker bug for the release, and conducts discussions this way.

This requires some extra thought on the part of developers, and we provide them a nicely documented process.

Bugzilla could take advantage of existing or new closing types or flags that mark a bug as worthy of a DOCUMENT note.

An email alias can start as an alias to a group doing the relnotes. It can later be channeled into a script to do interesting things, such as creating bugzilla entries.

We need a process doc that tells developers how to identify something that is worth documenting. This is a whole topic in itself. This might be driven by the scope of a specific document, or by general guidelines of the various audiences we write for.

Writing the content
The general idea here is to model the success that software projects have. Modularize the release notes, making individuals or small groups responsible for a piece of the relnotes. Work goes on in parallel, and at certain milestones (test, release candidate, release), the modules form like Voltron ... that is, connect together and receive a group edit/check.

These relnote module groups can interact more closely with the developers related to their content. A group of developers knows who is going to be asking and answering the documentation needs for a subject area. The doc writers and editors can become subject matter experts for their area.

For example, I could be accountable for gathering and writing the SELinux release notes beat and I use the same set of relationships to write the Fedora SELinux FAQ, and ultimately the Red Hat SELinux Guide. Everyone knows who to bring SELinux documentation questions to. I know which kernel, userspace, policy, and desktop people to go to for information throughout the release cycle, which mailing lists to read and so forth. This could extend into my life in other meaningful ways, as a writer, instructor, etc.

Here are some ideas for modules/areas of expertise. These would map directly to different parts of the relnotes. We work on separate sections as separate files and merge them with one parent XML file.


 * Kernel
 * Desktop
 * Printing
 * Server Configuration Tools
 * File Systems
 * File Servers
 * Web Servers
 * GCC/Development Tools
 * Security
 * Java
 * System Daemons (cron, etc.)
 * Sound and Video
 * X Window System (xorg)
 * Status of all Packages

'Update' These have been defined at  DocsProject/ReleaseNotes/Beats.

Each module can attract an individual or team, depending on the complexity.

For writers/editors, this gives a chance to work more closely with developers of material you are interested in. You can more easily spin off Fedora docs or your own, outside written works from this relationship.

Personally, if I wanted to write a book about managing Samba for Fedora Core, it would be advantageous if I were the release notes maintainer for Samba in Fedora, eh? ;-)