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.