Rephrase "two syntax variants" note to give readers a hint why they exist.

1 files changed, 13 insertions, 10 deletions

diff --git a/docs/src/two-syntax-variants-used b/docs/src/two-syntax-variants-used
index 4a9815345..af583a0a9 100644
--- a/docs/src/two-syntax-variants-used
+++ b/docs/src/two-syntax-variants-used
@@ -1,15 +1,18 @@
 .. note::
 
-    This page uses two different syntax variants: the Cython specific ``cdef`` syntax
-    and static Cython type declarations in
-    :ref:`pure Python code <pep484_type_annotations>`,
-    following `PEP-484 <https://www.python.org/dev/peps/pep-0484/>`_ type hints
-    and `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_ variable annotations.
-    To make good use of the latter, including C data types, etc., you need
-    the special ``cython`` module, which you can import with
+    This page uses two different syntax variants:
 
-    .. code-block:: python
+    * Cython specific ``cdef`` syntax, which was designed to make type declarations
+      concise and easily readable from a C/C++ perspective.
 
-        import cython
+    * Pure Python syntax which allows static Cython type declarations in
+      :ref:`pure Python code <pep484_type_annotations>`,
+      following `PEP-484 <https://www.python.org/dev/peps/pep-0484/>`_ type hints
+      and `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_ variable annotations.
 
-    in the Python module that you want to compile.
+      To make use of C data types in Python syntax, you need to import the special
+      ``cython`` module in the Python module that you want to compile, e.g.
+
+      .. code-block:: python
+
+          import cython