Here are the organization of some ideas generated during an impromptu
discussion on #fedora-docs.
The ideas here make doing the release notes fun, manageable, and a good
opportunity for writers and editors who want a closer interaction with
developers and the Fedora release process.
# Suppositions
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
2. bugzilla for all packages
3. easy-to-send-to email address
# The Pieces
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? ;-)
## Random thoughts
Can we rethink the release notes? Can these be more useful and
accessible for the general user? Or must one have some idea of Linux,
hardware, etc. in order to need the relnotes?
## 30 ##
--
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
Learn, Network and Experience Open Source.
Red Hat Summit, New Orleans 2005 http://www.redhat.com/promo/summit/
Attachment:
signature.asc
Description: This is a digitally signed message part
