doc: add rst header order recommendation

Ticket: #7396

diff --git a/doc/userguide/devguide/contributing/contribution-process.rst b/doc/userguide/devguide/contributing/contribution-process.rst
index 766122511b884e161c2b3bc8a777ce621ff4b09e..006fecf0352d338bbeadfcf5cbf3441a5e13ede8 100644 (file)
--- a/doc/userguide/devguide/contributing/contribution-process.rst
+++ b/doc/userguide/devguide/contributing/contribution-process.rst
@@ -224,8 +224,16 @@ We have a :ref:`Coding Style` that must be followed.
 Documentation Style
 ===================
 
-For documenting *code*, please follow Rust documentation and/or Doxygen
-guidelines, according to what your contribution is using (Rust or C).
+For documenting *code*, please follow Rust documentation and/or
+Doxygen guidelines, according to what your contribution is using (Rust
+or C). The rest of this section refers to the user and developer
+documentation.
+
+The user and developer guide documentation (what you are reading now)
+is written in *reStructuredText* and rendered with `Sphinx
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_. For
+a primer *reStucturedText* please see the `reStrucutredText Primer
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
 
 When writing or updating *documentation pages*, please:
 
@@ -236,6 +244,32 @@ When writing or updating *documentation pages*, please:
   /docs.suricata.io/en/latest/#suricata-user-guide>`_ and can also be
   built to pdf, so it is important that it looks good in such formats.
 
+Headings
+--------
+
+reStructuredText allows for flexible header order, for consistency
+please use the following order:
+
+* ``#``: for h1
+* ``*``: for h2
+* ``=``: for h3
+* ``-``: for h4
+* ``~``: for h5
+* ``^``: for h6
+
+For example, in a new documentation page:
+
+.. code-block:: rst
+
+  Page Title
+  ##########
+
+  Section
+  *******
+
+  Sub-Section
+  ===========
+
 Rule examples
 -------------