WIP

docs/admin.rst

@@ -1,14 +1,13 @@
 Server Administration
 ---------------------
 
-Python-arango provides operations to perform administrative tasks and monitor
-ArangoDB instances. For more information on the HTTP REST API for monitoring
-and administration visit this
+Python-arango provides operations for server administration and monitoring.
+For more information on the HTTP REST API visit this
 `page <https://docs.arangodb.com/HTTP/AdministrationAndMonitoring>`__.
 
 .. note::
-     Some operations require root privileges (i.e. the user must have
-     access to the ``_system`` database).
+     Some operations in the example below require root privileges (i.e. the
+     user must have access to the ``_system`` database).
 
 .. warning::
     `Replication <https://docs.arangodb.com/HTTP/Replications>`__ and

docs/aql.rst

@@ -1,22 +1,20 @@
 AQL
 ----
 
-**ArangoDB AQL Language (AQL)** is used to retrieve and modify the data stored
-in ArangoDB. AQL is similar to SQL for relational databases but without the
-support for data-definition operations such as *creating* or *deleting*
+**ArangoDB AQL Language (AQL)** is used to retrieve and modify data stored in
+ArangoDB. AQL is similar to SQL for relational databases but without the
+support for data-definition operations such as creating or deleting
 :doc:`databases <database>`, :doc:`collections <collection>` and
-:doc:`indexes <cindex>` etc.
-
-For more general information on AQL visit this
+:doc:`indexes <index>` etc. For more general information on AQL visit this
 `page <https://docs.arangodb.com/AQL>`__.
 
 AQL Queries
 ===========
 
-AQL queries can be invoked using the :ref:`AQL` class, which returns instances
-of the :ref:`Cursor` class. For more information on the syntax of AQL please
-visit this `page <https://docs.arangodb.com/AQL/Fundamentals/Syntax.html>`__
-and for more information on the HTTP REST API for AQL queries visit this
+**AQL queries** can be invoked using the :ref:`AQL` class, which returns
+instances of :ref:`Cursor`. For more information on the syntax of AQL visit
+this `page <https://docs.arangodb.com/AQL/Fundamentals/Syntax.html>`__ and
+for more information on the HTTP REST API visit this
 `page <https://docs.arangodb.com/HTTP/AqlQuery>`__.
 
 **Example:**
@@ -53,7 +51,7 @@ and for more information on the HTTP REST API for AQL queries visit this
 AQL User Functions
 ==================
 
-**AQL User Functions** are custom functions defined by the users to extend the
+**AQL user functions** are custom functions defined by the users to extend the
 functionality of AQL. Although python-arango provides ways to add, delete and
 retrieve user functions in Python, the functions themselves must be defined in
 Javascript.
@@ -88,13 +86,12 @@ Refer to the :ref:`AQL` class for more details on the methods above.
 AQL Query Cache
 ===============
 
-The purpose of **AQL Query Cache** is to minimize redundant calculation of the
-same query results. If it useful when read queries are called frequently and
-write queries are not.
+**AQL query cache** minimizes redundant calculation of the same query results.
+If it useful when read queries are called frequently and write queries are not.
 
 For more information on the HTTP REST API for AQL query caches visit this
 `page <https://docs.arangodb.com/HTTP/AqlQueryCache>`__ and for more general
-information this
+information visit this
 `page <https://docs.arangodb.com/AQL/ExecutionAndPerformance/QueryCache.html>`__.
 
 **Example:**
@@ -115,5 +112,4 @@ information this
     # Clear the AQL query cache
     db.aql.cache.clear()
 
-
 Refer to the :ref:`AQLQueryCache` class for more details on the methods above.

docs/async.rst

@@ -3,11 +3,11 @@ Async Execution
 
 Python-arango provides support for **asynchronous execution**, where incoming
 requests are placed in a server-side, in-memory task queue and executed in a
-*fire-and-forget* style. The results of the requests can be retrieved later via
+fire-and-forget style. The results of the requests can be retrieved later via
 :ref:`AsyncJob` objects.
 
-For more information on the HTTP REST API for asynchronous results visit this
-`page <https://docs.arangodb.com/HTTP/AsyncResultsManagement>`_.
+For more information on the HTTP REST API for retrieving asynchronous results
+visit this `page <https://docs.arangodb.com/HTTP/AsyncResultsManagement>`_.
 
 **Example:**