Cleanup README, reorganize some sections

Author: jamesls

README.rst

@@ -10,7 +10,7 @@ JMESPath
    :target: http://travis-ci.org/jmespath/jmespath.py
 
 
-JMESPath (pronounced ``\ˈjāmz path\``) allows you to declaratively specify how to
+JMESPath (pronounced "james path") allows you to declaratively specify how to
 extract elements from a JSON document.
 
 For example, given this document::
@@ -42,13 +42,42 @@ The ``*`` can also be used for hash types::
 
 The expression: ``foo.*.name`` will return ["one", "two"].
 
-Join us on our `Gitter channel <https://gitter.im/jmespath/chat>`__
-if you want to chat or if you have any questions.
+
+API
+===
+
+The ``jmespath.py`` library has two functions
+that operate on python data structures.  You can use ``search``
+and give it the jmespath expression and the data::
+
+    >>> import jmespath
+    >>> path = jmespath.search('foo.bar', {'foo': {'bar': 'baz'}})
+    'baz'
+
+Similar to the ``re`` module, you can use the ``compile`` function
+to compile the JMESPath expression and use this parsed expression
+to perform repeated searches::
+
+    >>> import jmespath
+    >>> expression = jmespath.compile('foo.bar')
+    >>> expression.search({'foo': {'bar': 'baz'}})
+    'baz'
+    >>> expression.search({'foo': {'bar': 'other'}})
+    'other'
+
+This is useful if you're going to use the same jmespath expression to
+search multiple documents.  This avoids having to reparse the
+JMESPath expression each time you search a new document.
 
 
 Specification
 =============
 
+If you'd like to learn more about the JMESPath language, you can check out
+the `JMESPath tutorial <http://jmespath.org/tutorial.html>`__.  Also check
+out the `JMESPath examples page <http://jmespath.org/examples.html>`__ for
+examples of more complex jmespath queries.
+
 The grammar is specified using ABNF, as described in
 `RFC4234 <http://www.ietf.org/rfc/rfc4234.txt>`_.
 You can find the most up to date
@@ -57,9 +86,6 @@ You can find the most up to date
 You can read the full
 `JMESPath specification here <http://jmespath.org/specification.html>`__.
 
-If you'd like to learn more about the JMESPath language, you can check out
-the `JMESPath tutorial <http://jmespath.org/tutorial.html>`__.
-
 
 Testing
 =======
@@ -70,26 +96,9 @@ there is a ``tests/compliance`` directory that contains
 to verify they are producing the correct output.  Each json
 file is grouped by feature.
 
-Python Library
-==============
 
-The included python implementation has two convenience functions
-that operate on python data structures.  You can use ``search``
-and give it the jmespath expression and the data::
-
-    >>> import jmespath
-    >>> path = jmespath.search('foo.bar', {'foo': {'bar': 'baz'}})
-    'baz'
-
-Similar to the ``re`` module, you can store the compiled expressions
-and reuse them to perform repeated searches::
-
-    >>> import jmespath
-    >>> path = jmespath.compile('foo.bar')
-    >>> path.search({'foo': {'bar': 'baz'}})
-    'baz'
-    >>> path.search({'foo': {'bar': 'other'}})
-    'other'
+Discuss
+=======
 
-You can also use the ``jmespath.parser.Parser`` class directly
-if you want more control.
+Join us on our `Gitter channel <https://gitter.im/jmespath/chat>`__
+if you want to chat or if you have any questions.