Update the documentation section

Also move it directly after the intro.

1 files changed, 26 insertions, 22 deletions

diff --git a/README.rst b/README.rst
index 4249347..cff59cb 100644
--- a/README.rst
+++ b/README.rst
@@ -88,6 +88,32 @@ Here are some other features:
 - **Internals that (mostly) mirror the C implementation**
   
   While being simpler to understand.
+  
+Documentation
+-------------
+
+Kconfiglib comes with extensive documentation in the form of docstrings. To view it, run e.g.
+the following command:
+
+.. code:: sh
+
+    $ pydoc kconfiglib
+    
+For HTML output, add ``-w``:
+
+.. code:: sh
+
+    $ pydoc -w kconfiglib
+    
+A good starting point is to read the module docstring (which you could also just read directly
+at the beginning of `kconfiglib.py <kconfiglib.py>`_). It gives an introduction to symbol
+values, the menu tree, and expressions.
+
+After reading the module docstring, a good next step is to read the ``Kconfig`` class
+documentation, and then the documentation for the ``Symbol``, ``Choice``, and ``MenuNode``
+classes.
+
+Please tell me if something is unclear to you or can be explained better.
 
 
 Installation
@@ -144,28 +170,6 @@ The entire library is contained in
 `kconfiglib.py <https://github.com/ulfalizer/Kconfiglib/blob/master/kconfiglib.py>`_.
 Just drop it somewhere.
 
-Documentation
--------------
-
-The (extensive) documentation is generated by running the following command in the same
-directory as `kconfiglib.py <https://github.com/ulfalizer/Kconfiglib/blob/master/kconfiglib.py>`_:
-
-.. code:: sh
-
-    $ pydoc kconfiglib
-
-For HTML output, use
-
-.. code:: sh
-
-    $ pydoc -w kconfiglib
-    
-You could also browse the docstrings directly in
-`kconfiglib.py <https://github.com/ulfalizer/Kconfiglib/blob/master/kconfiglib.py>`_.
-
-Please tell me if something is unclear to you or can be explained better. The Kconfig
-language has some dark corners.
-
 Examples
 --------