[RFC] relnotes process

[Karsten Wade]

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/

[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

[Colin Charles]

On Wed, 2005-03-16 at 10:51 -0500, Greg DeKoenigsberg wrote:
>  
>    * the audience.  I suggest fedora-maintainers for Extras
>  maintainers, 
>      and what, eng-list for Core? 
Shouldn't people on eng-list already be on fedora-maintainers?

fedora-maintainers is not only for Extras folk, its also for Core folk
-- 
Colin Charles, byte(a)aeon.com.my
http://www.bytebot.net/
"First they ignore you, then they laugh at you, then they fight you, 
then you win." -- Mohandas Gandhi

[Greg DeKoenigsberg]

>  Shouldn't people on eng-list already be on fedora-maintainers?
>  
>  fedora-maintainers is not only for Extras folk, its also for Core folk 
That's as may be, but mu guess is that the force of the message is greater
if it hits an internal mailing list as well.

--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