Archive:What to document for Fedora

From FedoraProject

Jump to: navigation, search

Contents

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