Great start. Comments inline.
On Wed, 16 Mar 2005, Karsten Wade wrote:
> 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
Critically important here is the Motherly Nag Process. If there's one
good legacy I left in RHN, it was the notion of nagging via clever email.
:)
To do this, we need:
* the audience. I suggest fedora-maintainers for Extras maintainers,
and what, eng-list for Core?
* the content. I'll send a separate sample email to the list. :)
> # 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.
Perhaps the best help here is a set of useful examples -- but you're
right; this is, as we say in NC, "a whole nother thang."
> ## 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.
Spot on. Responsibility, accountability, empowerment, engagement.
> 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?
Well done, Karsten.
--g
_____________________ ____________________________________________
Greg DeKoenigsberg ] [ the future masters of technology will have
Community Relations ] [ to be lighthearted and intelligent. the
Red Hat ] [ machine easily masters the grim and the
] [ dumb. --mcluhan
