I've made some small tweaks to the documentation

docs/source/architecture.rst

@@ -7,13 +7,17 @@ Architecture
 
 
 **Show**
-    A show is the program you tell to circus to run.  A single circus instance an run one or more shows.
+    A *show* is the program you tell Circus to run.  A single Circus
+    instance can run one or more shows.
 **Flies**
-    A fly is an independent OS process instance of your program. A single show can run one or more flies.
-**Trainer** 
-    The trainer is responsible for managing all the **Shows** within circus and ensures all the flies run correctly.
-**Controller** 
-    A controller contains the set of actions that con be perform on the trainer.
+    A *fly* is an independent OS process instance of your program.
+    A single show can run one or more flies.
+**Trainer**
+    The *trainer* is responsible for managing all the shows within circus,
+    ensuring all flies run correctly.
+**Controller**
+    A *controller* contains the set of actions that con be performed on
+    the trainer.
 **Client**
-    The client allows you to communicate with the **Controller** via ZMQ to control circus.
-
+    The *client* allows you to communicate with the controller via ZMQ to
+    control Circus.

docs/source/configuration.rst

@@ -1,7 +1,7 @@
 Configuration
 -------------
 
-Circus can be configured to run with an ini-style file. 
+Circus can be configured using an ini-style configuration file.
 
 Example::
 
@@ -18,19 +18,18 @@ Example::
 circus
 ~~~~~~
     **endpoint**
-        The endpoint where to bind the ZMQ socket.   
+        The endpoint to which the ZMQ socket will be bound.
     **check_delay**
         The polling interval for the ZMQ socket.
 
 
 show
 ~~~~
-    **cmd** 
+    **cmd**
         The executable program to run.
-    **args** 
-        Arguments to pass to the program.
-    **warmup_delay** 
-        The delay (in seconds) in between running flies.
+    **args**
+        Command-line arguments to pass to the program
+    **warmup_delay**
+        The delay (in seconds) between running flies.
     **num_flies**
         The number of flies to run for this show.
-

docs/source/index.rst

@@ -1,24 +1,25 @@
-Circus Process Watcher 
+Circus Process Watcher
 ======================
 
 .. image:: images/circus-medium.png
    :align: right
 
 Circus is a program that will let you run and watch multiple processes.
 
-Circus can be driven through a CLI or used via its APIs.
+Circus can be driven through a command-line interface, or programmatically
+through its APIs.
 
 It shares some of the goals Supervisord, BluePill and Daemontools.
 
 To install it, check out :ref:`installation`
 
 
-Using as a library
--------------------
+Using as a Library
+------------------
 
-Circus provides high-level Classes and functions that will let you run
-processes. For example, if you just want to run 4 workers forever, you
-can write.
+Circus provides high-level classes and functions that will let you run
+processes. For example, if you just want to run four workers forever, you
+can write:
 
 .. code-block:: python
 
@@ -30,19 +31,20 @@ can write.
     finally:
         trainer.stop()
 
-This snippet will run 3 *myprogram* processes and watch them for you, 
+This snippet will run instances of *myprogram* and watch them for you,
 restarting them if they die unexpectedly.
 
 To learn more about this, see :ref:`library`
 
 
-Using it through the command-line 
+Using it through the command-line
 ---------------------------------
 
-Circus provides a command line script that can be used to manage one or more 
-programs each running as one or more process instance.
+Circus provides a command-line script that can be used to manage one or
+more programs, each running as one or more process instance.
 
-It uses an ini-style file. Example::
+Circus's command-line tool is configurable using an ini-style
+configuration file. Here is a minimal example::
 
     [circus]
     check_delay = 5
@@ -58,8 +60,8 @@ The file is then run using *circusd*::
 
     $ circusd example.ini
 
-There's also a *circusctl* command line tool to query Circus to perform
-actions like adding or removing workers, or getting back some usage
+Circus also provides a management console, *circusctl*. You can use it to
+perform actions such as adding or removing workers or to display various
 statistics.
 
 To learn more about this, see :ref:`cli`

docs/source/library.rst

@@ -3,12 +3,13 @@
 Circus Library
 --------------
 
-The circus package is composed of a high-level :func:`get_trainer`
-function and many classes. In most cases, using the high level function
-should be enough, as it creates everything's needed for Circus to run.
+The Circus package is composed of a high-level :func:`get_trainer`
+function and many classes. In most cases, using the high-level function
+should be enough, as it creates everything that is needed for Circus to
+run.
 
-However, you can instanciate yourself underlying classes if you have
-specific needs.
+You can subclass Circus's classes if you need more granular
+configurability.
 
 
 .. autofunction:: circus.get_trainer