This page is where we explain how-to use this Wiki for writing release notes beats.
- Find the appropriate beat, such as Docs/Beats/Desktop , and edit your content into the page. There is a list of existing beats at Documentation Beats.
- If the page does not exist, create a new one, either at the top-level or as a sub-page, in the format of Docs/Beats/Beatname . Edit the main page at Docs/Beats to add it to the table of contents.
- Don't worry. Competent writers and editors are watching your contributions. We'll follow up with your contribution directly in the Wiki, cleaning, simplifying, formatting, and so forth.
For more details, read on:
How To Highlight Something for Documentation a/k/a *docs*
Six Ways of Submitting Content
This is your release note for that package or project; your contribution:
- Include any relevant references, mailing list discussions, etc.
- Bugzilla numbers
- As much writing as you can/want to do for this note; writers will return for clarification, and we can clean up your writing
In order of best to least best:
- Edit the content directly within the appropriate beat at Docs/Beats , using the same directions.
- Email relnotes@fedoraproject.org with all details.
- Add relnotes@fedoraproject.org as a Cc: in an existing bug report. Adding *docs* to a comments field identifies the field as the content you are referencing. Include all relevant information and writing.
- Change the fedora_requires_release_note flag on an existing Bugzilla entry to +
- Enter any release note requests, comments, etc. into this pre-filled bugzilla request , using the same directions.
- Include the
*docs*keyword in your CVS commit log ([#CVS-keyword-docs More...] ). Use this to mark milestone commits. This is your release note for that project/package.
You can get more information about what to document . This same content is included at the bottom of this page for your convenience.
Using CVS Commit Logs
CVS users can alert the Documentation Project to a particular commit by using the keyword *docs* in the commit log.
Examples might be a CVS commit that fulfills a feature, fixes a bug, or otherwise is worth noting in the relnotes
When you put the keyword *docs* in the commit log message, a copy of the commit is sent to relnotes@fedoraproject.org . The beat writers and editors parse the note into the proper place, or open a bugzilla report to track the note suggestion.
Using *docs* in Bugzilla
Use a comment field to summarize whatever you think is needing attention by the Documentation team. In that field, put the keyword *docs* at the top of the comment field.
What To Document
As a Fedora contributor, you have many ways to be sure something gets documented:
- Include the
*docs*keyword in your CVS commit log - Email to fedora-docs-project@redhat.com or relnotes@fedoraproject.org
- Edit the appropriate release notes beat at Docs/Beats
- File a bugzilla report
- Contact an author directly
- Add relnotes@fedoraproject.org to the Cc: in a bug report
You can read more about this at DocsProject/HighlightedForDocs .
The questions then become:
How Do I Know What Is Worth Documenting?
There is no hard rule about this. It is situational, and context matters. Some examples:
- You close a major bug with this commit. Include all relevent bugzilla numbers and the keyword
*docs*. - This commit represents a milestone in a feature. Include all relevant bugzilla numbers, other information, and the
*docs*keyword. - You want to document a workaround that is still required after this commit. Include all details, links to other documentation, and the
*docs*keyword.
This process is meant to be lightweight for you. The release notes beat writers may not do anything with your report. They may ask questions, in email or on mailing list, or file a bug report to track the discussion and make it a blocker against the release notes.
What Information Should I Put in the Email or Log Message?
The more the better. We may not use it all, but it's good to have all relevant and slightly-relevant information available. If you want, you can follow up with an email to relnotes@fedoraproject.org or file a bug against the release-notes in Fedora Documentation at http://bugzilla.redhat.com/ or using http://tinyurl.com/8lryk, which links to a pre-filled bugzilla request.
Should I Care About Style, Grammar, or Clarity?
You may not be writing the final document, but you do need to make sure the writer who gets your message will know what you mean. Be prepared to interact, if the writers needs clarification or confirmation.
Technical accuracy is important. Clarity of explanation is important.
We can edit the rest. :)
How Do I Follow Up on the Documentation Request?
You can choose what method you want, depending on your interest or need:
- Email to relnotes@fedoraproject.org goes to all beat writers
- Email to fedora-docs-list@redhat.com gets you a good audience that includes all the beat writers
- File a bugzilla with this pre-filled bug report
- Fill out more information on the appropriate Wiki beat page at Docs/Beats
Add Your Question Here
You need to be a recipient of email to relnotes@fedoraproject.org. This is a manual alias (for now), email kwade@redhat.com to be added. This address receives all bug reports assigned to relnotes@ (including the release-notes component in bugzilla), and all CVS commits that contain the *docs* keyword in the log message.
Read and understand about the release notes beats .
Keep to the Schedule
The documentation schedule for Fedora includes time for translation of content so that it all can be included within the ISOs.
Release notes are an ongoing process, with rolling releases throughout testing and after final release.
Gathering Raw Notes and Using the Wiki
Beat writers are now able to use the tree at Docs/Beats to gather raw input and form it into content for the release notes.
These pages have a light structure that generally goes one layer deep, for example, Docs/Beats/Kernel is for the kernel portion of the release notes.
Beat writers are free to add and change sub-pages, as they need. Other contributors can do the same. The only requirement to edit is that the user be registered and logged in.
Wiki-help for beat contributions is now on-topic for #fedora-docs.
Keeping a Relevant Beat
Beat writers need to keep the content cleaned-up and relevant. You want to watch your page and all sub-pages using the pattern Docs/Beats/Beatname.* in your "Subscribed wiki pages" of your UserPreferences.
Snapshots and Changes
These beat notes are ongoing workspaces. A snapshot is taken just prior to freeze for translation, and the content is merged into the overall DocBook/XML-based release notes, as per the FDP release schedule .
Beat writers need to keep the content cleaned-up and relevant. You want to watch the Docs/Beats/Beatname* pages for all changes.
Another snapshot may be taken one or two days before release, to capture any new content that came after the translation freeze snapsot. This secondary snapshot is used to create a latest release notes that is linked from the as-shipped release notes. This latest relnotes is published online at a fixed URL, and helps to make up for the loss of content that appeared or was changed after translation freeze.