DOCS-339 content review of geospatial index

Author: Sam Kleinman

draft/applications/geospatial-indexes.txt

@@ -4,14 +4,12 @@ Using Geospatial Data
 
 .. default-domain:: mongodb
 
-MongoDB supports location-based applications using geospatial
-coordinate with rich location aware queries that return documents
-based on location, and a special geospatial index type to support
-these queries. This document introduces geospatial data modeling,
-indexing operations, and queries using the special :ref:`geospatial
-query operators <geospatial-query-operators>`. For more information about
-the geospatial indexes and its operations see :doc:`Geospatial Indexes
-</core/geospatial-indexes>`.
+MongoDB provides rich location aware queries that return documents
+based on location with a special geospatial index type. This document
+introduces geospatial data modeling, indexing operations, and provides
+example queries using the :ref:`geospatial query operators
+<geospatial-query-operators>`. For more information about the
+geospatial indexes and operations see the :doc:`/applications/geospatial-indexes`.
 
 .. _geospatial-coordinates:
 
@@ -47,7 +45,7 @@ Exact
 ~~~~~
 
 You can use the :func:`find() <db.collection.find()>` method to query
-directly for an exact match on a location. These queries take the
+for an exact match on a location. These queries take the
 following prototypical form:
 
 .. code-block:: javascript
@@ -63,7 +61,7 @@ field that are exactly ``[ 42, 42 ]``, consider the following example:
 
    db.places.find( { "loc": [ 42, 42 ] } )
 
-Exact geospatial queries are only useful in a limited selection of
+Exact geospatial queries only have applicability for a limited selection of
 cases, :ref:`proximity <geospatial-query-proximity>` and :ref:`bounded
 <geospatial-query-bounded>` provide more useful results.
 
@@ -96,8 +94,8 @@ This operation will return documents from a collection named
 coordinates ``[ -74, 40.74 ]``.
 
 In addition to :operator:`near`, the :dbcommand:`geoNear` command
-provides equivalent geospatial query functionality, but provides
-additional options *and* returns additional information for each
+provides equivalent functionality. :dbcommand:`geoNear` adds
+additional options and returns more information for each
 document found. In its most simple form, the :dbcommand:`geoNear`
 command has the following prototype form:
 
@@ -166,25 +164,24 @@ provides the :operator:`$maxDistance` operator that you can use in
 
    db.runCommand( { geoNear: "collection", near: [ x, y ], maxDistance: z } )
 
-The distance specified in :operator:`maxDistance` is in the same units
-as the coordinate system specifed. For example, if the indexed
-location data is in meters, the distance unit is also in meters.
+Specify the distance in the ``maxDistance`` option using the same units
+as the coordinate system specified. For example, if the indexed
+location data is in meters, the distance units are also in meters.
 
 .. _geospatial-within:
 .. _geospatial-query-bounded:
 
 Bounded
 ~~~~~~~
 
-MongoDB provides the ability to return documents using geospatial
-index that have coordinates located inside of a bounded shape. Bounded
-queries use the :operator:`$within` operator, and MongoDB does not
-sort the result set. Because result sets from bounded queries are not
-sorted, they are faster than :ref:`proximity
+Bounded queries return results within the boundaries of a shape
+specified in the query. The :operator:`$within` operator allows you to
+construct these quires. Bounded queries do not return sorted results:
+as a result these queries are faster than :ref:`proximity
 <geospatial-query-proximity>` queries.
 
-The :operator:`$within` operator returns points within the following
-shapes:
+Using the :operator:`$within`, you can specify boundaries with the
+following shapes:
 
 - circles,
 - rectangles (i.e. "boxes,") or
@@ -322,7 +319,6 @@ you specify the ``{ spherical: true }`` option to the command.
    The radius of the Earth is ``3963.192`` miles or ``6378.137``
    kilometers.
 
-
 The following query would return documents from the ``places``
 collection, within the circle described by the center ``[ -74, 40.74 ]``
 with a radius of ``100`` kilometers:
@@ -429,4 +425,7 @@ in the following example:
 
    db.records.ensureIndex( { "addresses.loc": "2d" } )
 
+.. the following is a section about the limitations of geospatial
+   indexes in sharding:
+
 .. includes:: /includes/geospatial-sharding.rst