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>

diff --git a/doc/start/documenting-ceph.rst b/doc/start/documenting-ceph.rst
index f9b13452dc70ae2909d8e7ef7a3477b21a8c0410..97d809f90db6332794417aa3839443720e6ed840 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
 ---------------------------