User:Immanetize/Beats Redux

The Problem with Beats

Docs Beats have become confusing to work with. The categories we fit research data into for the Release Notes has been loosely based around RPM groups, but those groups don't tell writers *where* to look for information, or *who* to talk to. The scope of these beats is too large, and even then, it can be difficult to pick the best place for something. We've gotten away from the concept of "claiming" a beat, mostly because contributions have waned. Restructuring the beats to have a more clearly defined scope should make it easier for writers to begin research and prevent redundant efforts.

The structure of the Beats does not need to be reflected in the Release Notes. The proposed beat divisions are based around areas of community, not functionality, to aid in community participation. The beats are a research tool, not a draft document. The final Release Notes is fully focused on functionality, and content should be restructured when committed.

Basic Release Note structure

Each single item in the Release Notes should convey a useful amount of information about the software it represents, such as:

• What is the thing?
• What does it do?
• What's different about it in this release?
• How do I use it?
• Where do I learn more?

For example:

Coffee Pot Control Protocol - It's real!

The popular http server apache in Fedora 25 has gained the ability to communicate with RFC2324 compliant devices. Combined with a new driver abstraction layer called libperkybeans, web developers can now use Fedora to build applications that will manage and administer one of their organizations most important resources.

[ example code here ]

For more information on implementing this technology, refer to:

• http://www.ietf.org/rfc/rfc2324.txt
• example.org/libperkybeans/api-docs
• fedora_cookbook/brew_coffee.html

Proposed New Beats

Easy Beats

System Wide Changes

Covers topics addressed in http://fedoraproject.org/wiki/Releases/21/ChangeSet#Fedora_21_Accepted_System_Wide_Changes_Proposals .

Self Contained Changes

Covers topics addressed in http://fedoraproject.org/wiki/Releases/21/ChangeSet#Fedora_21_Accepted_Self_Contained_Changes_Proposals

Change Beats SOP

• Each Change proposal has a tracking bug. Writers who wish to cover a specific Change should identify themselves as the "Docs Contact" in that tracking bug.

• Each Change proposal is announced and discussed on the devel@ mailing list. Writers should read the threads related to their Change, ideally participating in that discussion, and ensure that concerns about documentation and usage of the change are adequately represented in the Release notes.

• Writers should communicate with the developers involved to draft copy, and check in with them at milestones to ensure the copy is relevant, accurate, and adequate.

• Ideally, the workload for covering *all* Changes would be distributed among a large number of writers. Someone should also volunteer to wrangle for each class of Change, assisting in coordinating other writers and picking up the slack as needed.

• Assignments should begin as soon as Change proposals are presented for discussion.

Critical Path Beats

A defined set of packages that can be listed via yum groups info @groupname.

The package sets can be covered by a single writer, or coordinated between a few, but the changes in each of these important packages should be documented.

Special Interest Group Beats

Sub-communities of the Fedora Project based around special interests have developed into SIGs. Members of SIGs collaborate their packaging efforts and often have dedicated mailing lists.

While not all SIGs appear active on their mailing lists, their members may still be active. Working a SIG beat may include researching past SIG efforts, defining a set of packages, reaching out to maintainers in the SIG, and checking pkgdb to see what those maintainers have been up to recently.

To keep this kind of persistent, secondary research separate from release-specific content, use the beat's Talk: page for notes.

https://fedoraproject.org/wiki/Category:SIGs has a list of groups that should be reviewed for writer assignment. A SIG Beats wrangler could reach out to these groups to see if a member might volunteer to cover the beat, or coordinate efforts between existing writers.