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 *docs*, 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? ;-)