doc/start: update documenting-ceph.rst (1 of x)

This PR updates the content on documenting-ceph,
which is, as of December 2021, in need of an
update.

This is the first of what I estimate to be three
to five PRs against this .rst file.

Signed-off-by: Zac Dover <zac.dover@gmail.com>

diff --git a/doc/start/documenting-ceph.rst b/doc/start/documenting-ceph.rst
index 97a1d1a66ad194d50004f652e1020f08581041b3..91c478d940506efa9326322cfeb0f3c51cdcfa7d 100644 (file)
--- a/doc/start/documenting-ceph.rst
+++ b/doc/start/documenting-ceph.rst
@@ -2,26 +2,49 @@
  Documenting Ceph
 ==================
 
-The **easiest way** to help the Ceph project is to contribute to the
-documentation. As the Ceph user base grows and the development pace quickens, an
-increasing number of people are updating the documentation and adding new
-information. Even small contributions like fixing spelling errors or clarifying
-instructions will help the Ceph project immensely.
-
-The Ceph documentation source resides in the ``ceph/doc`` directory of the Ceph
-repository, and Python Sphinx renders the source into HTML and manpages. The
-https://docs.ceph.com link currently displays the ``master`` branch by default,
-but you may view documentation for older branches (e.g., ``mimic``) by substituting
-``latest`` in the URL with the branch name you prefer.
-
+You can help the Ceph project by contributing to the documentation.  Even
+small contributions help the Ceph project, such as fixing
+spelling errors or rewriting confusing instructions.
+
+The easiest way to suggest a correction to the documentation is to send an
+email to `ceph-users@ceph.io`. Include the string "ATTN: DOCS" or
+"Attention: Docs" or "Attention: Documentation" in the subject line.  In
+the body of the email, include the text to be corrected (so that I can find
+it in the repo) and include your correction.
+
+Another way to suggest a documentation correction is to make a pull request.
+The instructions for making a pull request against the Ceph documentation are
+in the section :ref:`making_contributions`.
+
+If this is your first time making an improvement to the documentation or
+if you have noticed a small mistake (such as a spelling error or a typo),
+it will be easier to send an email than to make a pull request. You will
+be credited for the improvement unless you instruct Ceph Upstream
+Documentation not to credit you.
+
+Location of the Documentation in the Repository
+===============================================
+
+The Ceph documentation source is in the ``ceph/doc`` directory of the Ceph
+repository. Python Sphinx renders the source into HTML and manpages. 
+
+Viewing Old Ceph Documentation
+==============================
+The https://docs.ceph.com link displays the ``master`` branch by default, but
+you can view the documentation for older versions of Ceph (e.g., ``mimic``) by
+replacing the version name in the url (e.g. ``pacific`` in
+`https://docs.ceph.com/en/pacific <https://docs.ceph.com/en/pacific>`_) with the
+branch name you prefer (e.g. ``mimic``, to create a URL that reads
+`https://docs.ceph.com/en/mimic/ <https://docs.ceph.com/en/mimic/>`_).
+
+.. _making_contributions:
 
 Making Contributions
 ====================
 
-Making a documentation contribution generally involves the same procedural
-sequence as making a code contribution, except that you must build documentation
-source instead of compiling program source. The sequence includes the following
-steps:
+Making a documentation contribution involves the same basic procedure as making
+a code contribution, with one exception: you must build documentation source
+instead of compiling program source. This sequence (the sequence of building the documentation source) includes the following steps:
 
 #. `Get the Source`_
 #. `Select a Branch`_