Review and update partition content. (#332)
diff --git a/src/api/database/partitions.rst b/src/api/database/partitions.rst
index 37337a6..a07fd43 100644
--- a/src/api/database/partitions.rst
+++ b/src/api/database/partitions.rst
@@ -13,26 +13,25 @@
.. _api/db/_partition:
Ordinarily, the documents inside a database are arbitrarily assigned
-into a shard range. This has an adverse affect on query performance as
-it is necessary to contact every shard range to answer each query (it
-is not possible to know, a priori, which shard ranges have no
-matches).
+into a shard range. This arbitrary assignment has an adverse affect on query performance
+because it is then necessary to contact every shard range to answer each query (it
+is not possible to know, a priori, which shard ranges have no matches).
A partitioned database (created with ``?partitioned=true``) provides a
-solution to this if your use case is suitable. All documents within a
-partitioned database have a special format for their document id's
+solution to this predicament if your use case is suitable. All documents within a
+partitioned database have a special format for their document IDs.
.. code-block:: text
partition:id
-Where both ``partition`` and ``id`` adhere to the CouchDB document id
+Where both ``partition`` and ``id`` adhere to the CouchDB document ID
restrictions.
Documents with the same ``partition`` value are placed in the same shard
-range as each other. You should choose your ``partition`` values with
+range with one another. You must choose your ``partition`` values with
care, the scalability and performance of this feature critically
-depends on it; ideally you have a natural choice in your application
+depends on it. Ideally, you have a natural choice in your application
(user name or account name, for example) that partitions your data
such that each partition can be queried meaningfully.
@@ -76,10 +75,10 @@
==================================
.. http:post:: /{db}/_partition/{partition}/_find
- :synopsis: Find documents inside a specific partition
-
- Find documents inside a specific partition, see the main
- documentation for :ref:`_find <api/db/_find>`.
+ :synopsis: Finds documents inside the specified partition
+
+ Finds documents inside the specified partition. See the CouchDB
+ documentation for more information about :ref:`_find <api/db/_find>`.
:param db: Database name
:param partition: Partition name
