fixes gh-1880 recommend using *, then - in list-tables (#2041)

* fixes gh-1880 recommend using *, then - in list-tables

* apply suggestions after review

Author: Onvember

doc/contributing/docs/markup/_includes/table.rst

@@ -0,0 +1,11 @@
+..  container:: table
+
+    ..  list-table::
+        :widths: 25 75
+        :header-rows: 1
+
+        *   -   Name
+            -   Use
+
+        *   -   :doc:`/reference/reference_lua/box_ctl/wait_ro`
+            -   Wait until ``box.info.ro`` is true

doc/contributing/docs/markup/intro.rst

@@ -11,11 +11,11 @@ Text can be organized in bullet-lists:
 
 ..  code-block:: rst
 
-    - This is a bullet list.
+    *   This is a bullet list.
 
-    - Bullets can be "*", "+", or "-".
+    *   Bullets can be "*", "+", or "-".
 
-        * Lists can be nested. And it is good to indent them with 4 spaces.
+        -   Lists can be nested. And it is good to indent them with 4 spaces.
 
 or in enumerated lists:
 

doc/contributing/docs/markup/tables.rst

@@ -5,15 +5,15 @@ Tables are very useful and rST markup
 `offers <https://docutils.sourceforge.io/docs/ref/rst/directives.html#tables>`_
 different ways to create them.
 
-We prefer list-tables to create table of contents:
+We prefer list-tables because they allow you to put as much content as you need
+without painting ASCII-style borders:
 
-..  code-block:: rst
+..  literalinclude:: _includes/table.rst
+    :language: rst
 
-    ..  container:: table
+This is how the table will look like:
 
-        ..  list-table::
-            :widths: 25 75
-            :header-rows: 1
+..  include:: _includes/table.rst
 
-            *   - Name
-                - Use
+Notice that we use ``*`` and then ``-`` in tables because it is more readable
+when rows and columns marked differently.