move images and cross references IQSS#10531

doc/sphinx-guides/source/contributor/documentation.md

@@ -42,3 +42,15 @@ If the page is written in Markdown (.md), use this form:
     :local:
     :depth: 3
     ```
+
+## Images
+
+A good documentation is just like a website enhanced and upgraded by adding high quality and self-explanatory images.  Often images depict a lot of written text in a simple manner. Within our Sphinx docs, you can add them in two ways: a) add a PNG image directly and include or b) use inline description languages like GraphViz (current only option).
+
+While PNGs in the git repo can be linked directly via URL, Sphinx-generated images do not need a manual step and might provide higher visual quality. Especially in terms of quality of content, generated images can be extendend and improved by a textbased and reviewable commit, without needing raw data or source files and no diff around.
+
+TODO: The above covers "how" but what about "when"?
+
+## Cross References
+
+When adding ReStructured Text (.rst) [cross references](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role), use the hyphen character (`-`) as the word separator for the cross reference label. For example, `my-reference-label` would be the preferred label for a cross reference as opposed to, for example, `my_reference_label`.

doc/sphinx-guides/source/developers/documentation.rst

@@ -106,24 +106,6 @@ You can click on the files in the ``html`` folder to preview the changes.
 
 Now you can make a commit with the changes to your own fork in GitHub and submit a pull request. See :ref:`how-to-make-a-pull-request`.
 
-Images
-------
-
-A good documentation is just like a website enhanced and upgraded by adding high quality and self-explanatory images.
-Often images depict a lot of written text in a simple manner. Within our Sphinx docs, you can add them in two ways: a) add a
-PNG image directly and include or b) use inline description languages like GraphViz (current only option).
-
-While PNGs in the git repo can be linked directly via URL, Sphinx-generated images do not need a manual step and might
-provide higher visual quality. Especially in terms of quality of content, generated images can be extendend and improved
-by a textbased and reviewable commit, without needing raw data or source files and no diff around.
-
-TODO: The above covers "how" but what about "when"?
-
-Cross References
-----------------
-
-**NOTE:** When adding ReStructured Text (RST) `cross references <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_, use the hyphen character (``-``) as the word separator for the cross reference label. For example, ``my-reference-label`` would be the preferred label for a cross reference as opposed to, for example, ``my_reference_label``.
-
 Versions
 --------