doc(guide): Improve and correct the prose across several documentation pages

Edit the prose in the existing documentation for clarity and correctness.

Closes #296

README.md

@@ -95,9 +95,6 @@ We have started documenting the library at http://falcon.readthedocs.org and we
 
 The docstrings in the Falcon code base are quite extensive, and we recommend keeping a REPL running while learning the framework so that you can query the various modules and classes as you have questions.
 
-You can also check out [Zaqar's WSGI driver](https://github.com/openstack/zaqar/tree/master/zaqar/queues/transport/wsgi) to get a feel for how you might
-leverage Falcon in building a REST API.
-
 The Falcon community maintains a mailing list that you can use to share
 your ideas and ask questions about the framework. We use the appropriately
 minimalistic [Librelist](http://librelist.com/) to host the discussions.

doc/api/hooks.rst

@@ -4,10 +4,11 @@ Hooks
 =====
 
 Falcon supports both **before** and **after** hooks. You install a hook simply by
-applying one of the decorators below either to an individual responder or
+applying one of the decorators below, either to an individual responder or
 to an entire resource.
 
-For example, suppose you had a hook like this:
+For example, consider this hook that validates a POST request for
+an image resource:
 
 .. code:: python
 
@@ -16,7 +17,7 @@ For example, suppose you had a hook like this:
             msg = 'Image type not allowed. Must be PNG, JPEG, or GIF'
             raise falcon.HTTPBadRequest('Bad request', msg)
 
-You would attach the hook to an ``on_post`` responder like so:
+You would attach this hook to an ``on_post`` responder like so:
 
 .. code:: python
 
@@ -24,22 +25,26 @@ You would attach the hook to an ``on_post`` responder like so:
     def on_post(self, req, resp):
         pass
 
-Or, if you had a hook that you would like to applied to *all*
-responders for a given resource, you could install the hook like this:
+Or, suppose you had a hook that you would like to apply to *all*
+responders for a given resource. In that case, you would simply
+decorate the resource class:
 
 .. code:: python
 
     @falcon.before(extract_project_id)
     class Message(object):
-        pass
+        def on_post(self, req, resp):
+            pass
 
-And you can apply hooks globally by passing them into the API class
-initializer (note that this does not require the use of a decorator):
-
-.. code:: python
-
-    falcon.API(before=[extract_project_id])
+        def on_get(self, req, resp):
+            pass
 
+Falcon middleware components can also be used to insert logic before and
+after requests. Unlike hooks, however, middleware components are
+triggered **globally** for all requests. This feature is
+documented in the
+:ref:`API class <api>` reference and the
+:ref:`Quickstart <quickstart-more-features>` example code.
 
 .. automodule:: falcon
     :members: before, after

doc/community/contribute.rst

@@ -50,7 +50,7 @@ doesn't make pyflakes sad.
 * Use whitespace to separate logical blocks of code and to improve readability.
 * Do not use single-character variable names except for trivial indexes when
   looping, or in mathematical expressions implementing well-known formulae.
-* Heavily document code that is especially complex and/or clever.
+* Heavily document code that is especially complex or clever!
 * When in doubt, optimize for readability.
 
 .. _napolean-flavored: http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html#example-google-style-python-docstrings

doc/community/faq.rst

@@ -17,9 +17,7 @@ simply wrap your api instance with a middleware app. For example:
 
     app = some_middleware.DoSomethingFancy(my_restful_service.api)
 
-See also the `WSGI middleware example <http://legacy.python.org/dev/peps/pep-3333/#middleware-components-that-play-both-sides>`_ given in PEP-3333. Note that use of Paste for wiring up
-middleware is discouraged these days, because that package is not
-well-maintained, and is incompatible with Python 3.
+See also the `WSGI middleware example <http://legacy.python.org/dev/peps/pep-3333/#middleware-components-that-play-both-sides>`_ given in PEP-3333.
 
 
 Why doesn't Falcon include X?
@@ -46,7 +44,7 @@ have full access to the Request and Response objects.
 
 .. code:: python
 
-    def auth(req, resp, params):
+    def auth(req, resp, resource, params):
         token = req.get_header('X-Auth-Token')
 
         if token is None:

doc/conf.py

@@ -55,7 +55,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Falcon'
-copyright = u'2014, Kurt Griffiths and Rackspace Hosting'
+copyright = u'2015, Kurt Griffiths and Rackspace Hosting'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

doc/user/big-picture-snip.rst

@@ -1,10 +1,6 @@
 The Big Picture
 ---------------
 
-Falcon encourages composition over inheritance in order to extend the
-functionality of the framework. This helps make applications easier to
-maintain and refactor over time.
-
 .. image:: ../_static/img/my-web-app.png
     :alt: Falcon-based web application architecture
-    :width: 600
+    :width: 600

doc/user/intro.rst

@@ -3,23 +3,26 @@
 Introduction
 ============
 
-Falcon is a minimalist, high-performance web framework for building web services and app backends with Python. It's WSGI-based, and works great with Python 2.6, Python 2.7, Python 3.3, Python 3.4 and PyPy, giving you a wide variety of deployment options.
+Falcon is a minimalist, high-performance web framework for building RESTful services and app backends with Python. Falcon works with any WSGI container that is compliant with PEP-3333, and works great with Python 2.6, Python 2.7, Python 3.3, Python 3.4 and PyPy, giving you a wide variety of deployment options.
 
 
 How is Falcon different?
 ------------------------
 
-First, Falcon is one of the fastest WSGI frameworks on the planet, and we are always trying to make it perform even better. When there is a conflict between saving the developer a few keystrokes and saving a few microseconds to serve a request, Falcon is strongly biased toward the latter. Falcon strives to strike a good balance between usability and speed.
+First, Falcon is one of the fastest WSGI frameworks available. When there is a conflict between saving the developer a few keystrokes and saving a few microseconds to serve a request, Falcon is strongly biased toward the latter. That being said, Falcon strives to strike a good balance between usability and speed.
 
-Second, Falcon is lean. It doesn't try to be everything to everyone, focusing instead on a single use case: HTTP APIs. Falcon doesn't include a template engine, form helpers, or an ORM (although those are easy enough to add yourself). When you sit down to write a web service with Falcon, you choose your own adventure in terms of async I/O, serialization, data access, etc. In fact, the only dependencies Falcon takes is on six, to make it easier to support both Python 2 and 3, and on mimeparse for handling complex Accept headers.
+Second, Falcon is lean. It doesn't try to be everything to everyone, focusing instead on a single use case: HTTP APIs. Falcon doesn't include a template engine, form helpers, or an ORM (although those are easy enough to add yourself). When you sit down to write a web service with Falcon, you choose your own adventure in terms of async I/O, serialization, data access, etc. In fact, Falcon only has two dependencies: `six`_, to make it easier to support both Python 2 and 3, and `mimeparse`_ for handling complex Accept headers. Neither of these packages pull in any further dependencies of their own.
 
-Third, Falcon eschews magic. When you use the framework, it's pretty obvious which inputs lead to which outputs. Also, it's blatantly obvious where variables originate. All this makes it easier for you and your posterity to reason about your code, even months (or years) after you wrote it.
+Third, Falcon eschews magic. When you use the framework, it's pretty obvious which inputs lead to which outputs. Also, it's blatantly obvious where variables originate. All this makes it easier to reason about the code and to debug edge cases in large-scale deployments of your application.
+
+.. _`six`: http://pythonhosted.org/six/
+.. _`mimeparse`: https://code.google.com/p/mimeparse/
 
 
 About Apache 2.0
 ----------------
 
-Falcon is released under the terms of the `Apache 2.0 License`_. This means you can use it in your commercial applications without having to also open-source your own code. It also means that if someone happens to contribute code that is associated with a patent, you are granted a free license to use said patent. That's a pretty sweet deal.
+Falcon is released under the terms of the `Apache 2.0 License`_. This means that you can use it in your commercial applications without having to also open-source your own code. It also means that if someone happens to contribute code that is associated with a patent, you are granted a free license to use said patent. That's a pretty sweet deal.
 
 Now, if you do make changes to Falcon itself, please consider contributing your awesome work back to the community.
 
@@ -29,4 +32,4 @@ Now, if you do make changes to Falcon itself, please consider contributing your
 Falcon License
 --------------
 
-    .. include:: ../../LICENSE
+.. include:: ../../LICENSE

doc/user/quickstart.rst

@@ -60,6 +60,7 @@ Then, in another terminal:
 
     $ curl localhost:8000/things
 
+.. _quickstart-more-features:
 
 More Features
 -------------

doc/user/tutorial.rst

@@ -3,10 +3,9 @@
 Tutorial
 ========
 
-This page walks you through building an API for a simple image-sharing
-service. Along the way, you will learn about Falcon's features and the
-terminology used by the framework. You'll also learn how to query Falcon's
-docstrings, and get a quick overview of the WSGI standard.
+In this tutorial we'll walk through building an API for a simple image sharing
+service. Along the way, we'll discuss Falcon's major features and introduce
+the terminology used by the framework.
 
 
 .. include:: big-picture-snip.rst