[RFC] relnotes process

[Greg DeKoenigsberg]

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