Normally the release notes process uses bugzilla entries to track all requests, so nothing is lost between the cracks. The relnotes are composed in !DocBook, output to HTML and plain text. The HTML is specially formatted to work in Anaconda during installation.
To get involved, join and send an email to [[MailTo(fedora DASH docs DASH list AT redhat DOT com)] .
For just this one time, we are experimenting with using a Wiki to capture changes from developers. Go get your hands dirty.
If you find something that needs changing:
1. Figure out exactly what you need to change or add before editing 1. Be sure the Wiki page is unlocked 1. Edit the page, which gives you a 15-minute lock 1. Try to complete the edit and submit within the 15-minutes, use the Preview to extend if you need to
Editors are subscribed to the page and will watch it for changes. Current editors include KarstenWade and StuartEllis. We'll respond ASAP to fix any grammatical, language, formatting, etc. errors. During our editing hours, we can be found on #fedora-docs on freenode .
If you are totally stuck and cannot get a change to work, are a WikiPhobe, or have lots of important stuff to add and no time to add it, you can send a detailed email to [[MailTo(fedora DASH docs DASH list AT redhat DOT com)] .
Even better, use this pre-filled bugzilla request .
We reserve the right to update this process in realtime, via the Wiki page and announcements to [[MailTo(fedora DASH maintainers AT redhat.com)] .
And here we go with just such a change ...
Release Notes Process - Iteration One, April 2005
Suppositions About the Relnotes
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 could use unique keywords in the comments such as DOXEN or RELNOTES, and a longer description explaining the change. Similar for changes to packages overall. Then we have to work with release engineering (rel-eng) to automate the extraction of that content.
Doc teams can then work on the content throughout the development process. For example, a weekly script extracts the useful pieces and generates populated bugzilla reports for each special KEYWORD by team type.
This requires some extra thought on the part of developers, and we'll 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 section, 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.
Here are some ideas for modules/areas of expertise. These would map directly to different parts of the relnotes. We work on separate <section>s as separate files and merge them with one parent XML file.
- kernel
- installer
- hardware/drivers
- packages (added, moved to extra, deprecated, AKA "package watch")
- server groups
- Apache
- Samba
- ...
- Misc daemons
- security groups
- SELinux
- ExecShield/PIE
- ...
- networking
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? ;-)