Docs Project workflow - beat writing

Beat writing is often a contributor's first exposure to working with the Fedora project. It is fun, because the beat writer gets to learn about the new things coming up in the next release of Fedora. It is relatively simple, technically, since most of the work is done in the wiki, but also since the work is done in the wiki, it is out in the open and easy to get input from more experienced contributors.

Selecting a beat

Beat writers sign up for beats on the Documentation Beats page. The list of beats is carried over from the previous release. If there is a need for a new beat it can easily be added. Each release of Fedora has a different flavor, and in some releases there may be no significant updates to a beat. In other releases there may be some significant changes for which there was no beat in the previous release.

Collecting Data

Beat writers have a variety of resources at their disposal for identifying what will appear in the next release of Fedora. A particular beat writer might not exploit all of these resources; each beat is different and each beat writer is different. The following are some of the assets the beat writer might exploit.

Developer Contact

Many beats have a developer contact listed. This can be a good way to get some insight into what is happening in that area. However, each release of Fedora updates thousands of packages. Chances are no one individual is aware of all that is happening, even in a particular area, so additional research is usually required.

Change Proposals

Proposals for changes in the next release of Fedora are documented on pages in the wiki. Change proposals contain information about the status of the change, the benefits that it will bring to Fedora, how it will affect the user experience and links to additional documentation. The Changes page contains links to the change set for each release and each change set page contains links to the individual change proposals.

Rawhide

Packages to be included in the next release of Fedora must first be in Rawhide. This means that the beat writer can install a new package from Rawhide and experiment with it well before the release. Of course, not all dependencies might be in the previous release, so sometimes installing an experimental package can have a cascading effect. For this reason, it may make sense to do a rawhide install to a stick or virtual machine.

The beat writer must also keep in mind that all features appearing in Rawhide might not become accepted features for the upcoming release, and once past feature freeze, many developers will begin working on the next+1 release, and that work will appear in Rawhide.

Often it is useful to download the SRPM from Rawhide. The changelog and NEWS files in the package are frequently more up-to-date than online resources, and occasionally there are additional clues in the SRPM. The SRPM can be browsed with file-roller, so the writer need not have a system on which the package can be installed.

Alpha and Beta

The Alpha and Beta releases give an early view of the next release. Alpha is generally a good time, Beta comes a bit late for release notes, although it can be good for last-minute checks.

Not everyone can afford to dedicate a machine to test on, however, so there are two ways you can run the Alpha or Beta software conveniently:

• Virtualization - running test software in a VM is by far the most convenient. Installing a new virtual machine on Fedora is simple and painless. However, there are two constraints that may prevent you from using this approach:

• • You need a machine with virtualization support

• • You need lots of memory

• USB Stick - You can use the Live USB Creator to install the Alpha or Beta on a USB thumb drive. You may then boot to the thumb drive and experiment with the new software. The thumb drive allows you to create documents, perform configurations, install software, and perform other operations that you might not be able to do on a LiveCD. However, the USB drive is significantly slower than a hard drive, so performance changes might not be obvious.

Dev List

One of the better ways to stay abreast of changes is to follow the Development mailing list. However, this is a high volume list, and keeping up can be a bit of a chore. And like any high volume list, there can be significant debate and off-topic discussions. Nonetheless, it can be a valuable resource for the beat writer.

Technical Notes

Early in the cycle a version of the Fedora Technical Notes will be produced for the upcoming version. Initially, this will be a list of all changes between Rawhide and the previous release of Fedora. While this can be a valuable resource, keep in mind that not all changes listed will actually make it into the next release.

The Technical Notes will be updated several times during the lead-up to the release. The day following the release the Notes will contain the differences between the current release and the previous.

Upstream release notes

Each entry in the Fedora Technical Notes includes a link to the upstream web site. Often these web pages link to the upstream release notes. When available, this is usually the beat writer's best resource. Unfortunately, not all upstream projects maintain release notes, and many projects keep them well hidden.

The actual writing

For major features that have feature pages, the beat writer may begin by simply pasting the release notes content from the feature page into the beat. The writer may make some notes on the page during the course of the research, or may even ask the developer to provide some prose. It is good to get content onto the beat page early, even if it is not in final form, so that others can review it and possibly catch issues that the beat writer might not be aware of.

Eventually, the beat writer wants to clean up the prose and convert it to "release notes speak". The writer should review the Docs Project Style Guide during this process as a reminder of some of the issues around presenting a consistent style across the Release Notes.

The Fedora Release Notes tend to be fairly high level. The writer should include a link to the upstream release notes where they are available. The writer should also be sure to note any places where an upgrade will require the user to take action. It is fairly common for changes to be required in configuration files, for example. For databases, the user will often need to export the database before the upgrade and import it after. These kinds of issues should be highlighted.

Note that not every change needs to be documented in the Release Notes. The notes should contain significant changes, but all changes are noted in the Fedora Technical Notes , so repetitive paragraphs of the form "A was upgraded from B to C" are unnecessary.

Markup

The conversion to XML will go much easier if the writer is careful to use consistent markup on the wiki. Several key items:

Package names should be marked with three quotes

'''packagename'''

File and directories should be marked as

<code>/dir/name</code>

Commands should NOT be indented. e.g.:

<code>
yum check-update
</code>

GUI menus and items should be marked

''About Me''

Keystrokes

'''[Key]'''

In general, you want to start discussion of a new package with a new subsection:

== postgresql ==

None of these are cast in bronze, but following these guidelines will make the conversion to XML a lot easier.