diff --git a/doc/contributing/docs/_includes/indentation.rst b/doc/contributing/docs/_includes/indentation.rst
index 67d4f85270..fd95c4c791 100644
--- a/doc/contributing/docs/_includes/indentation.rst
+++ b/doc/contributing/docs/_includes/indentation.rst
@@ -1,10 +1,16 @@
-#.  list item 1
-#.  list item 2
+|...|...|...|...
+#.  List item 1.
+    Paragraph continues.
 
-    *   nested list item
+    Second paragraph.
+
+#.  List item 2.
+
+    *   Nested list item.
 
         ..  code-block:: bash
 
-            # this is a code block inside a nested list item
+            # this code block is in a nested list item
 
-    *   another nested list item
\ No newline at end of file
+    *   Another nested list item.
+|...|...|...|...
diff --git a/doc/contributing/docs/markup.rst b/doc/contributing/docs/markup.rst
index cb33160999..e7413942d9 100644
--- a/doc/contributing/docs/markup.rst
+++ b/doc/contributing/docs/markup.rst
@@ -67,6 +67,17 @@ It's best if all indents are multiples of 4 spaces, even in lists. Otherwise
 the document is not consistent. Also, it is much easier to put indents
 with tabs than manually.
 
+Note that you have to use two or three spaces instead of one.
+It is allowed in rST markup:
+
+..  code-block:: rst
+
+    |...|...|...|...
+    *   unordered list
+    #.  ordered list
+    ..  directive::
+    |...|...|...|...
+
 Example:
 
 ..  literalinclude:: _includes/indentation.rst
@@ -74,7 +85,9 @@ Example:
 
 Resulting output:
 
-..  include:: _includes/indentation.rst
+    ..  include:: _includes/indentation.rst
+        :start-line: 1
+        :end-line: -1
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Code snippets