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