doc/start: update linking conventions

Update linking conventions in doc/start/documenting-ceph.rst, as
requested in
https://github.com/ceph/ceph/pull/49889#issuecomment-1657750905 by
bluikko. This commit introduces a convention that could be read as
inconsistent with other conventions mentioned on the page altered by
this commit. Future PRs will attenuate this inconsistency.

Signed-off-by: Zac Dover <zac.dover@proton.me>
(cherry picked from commit 52e8ec076f7bc65c13f61608b2a4ee0093569947)

diff --git a/doc/start/documenting-ceph.rst b/doc/start/documenting-ceph.rst
index 3e088467525216809d97ffce5dc2b075fc4a9c3e..e9336140029fbddae5c67011bca81b8f42a349a2 100644 (file)
--- a/doc/start/documenting-ceph.rst
+++ b/doc/start/documenting-ceph.rst
@@ -973,6 +973,15 @@ convention was preferred because it made the documents more readable in a
 command line interface. As of 2023, though, we have no preference for one over
 the other. Use whichever convention makes the text easier to read.
 
+Using a part of a sentence as a hyperlink, `like this <docs.ceph.com>`_, is
+discouraged. The convention of writing "See X" is preferred. Here are some
+preferred formulations:
+
+#. For more information, see `docs.ceph.com <docs.ceph.com>`_.
+
+#. See `docs.ceph.com <docs.ceph.com>`_.
+
+
 Quirks of ReStructured Text
 ---------------------------