Update master

Author: matulef

draft/core/indexes.txt

@@ -163,7 +163,7 @@ Compound Indexes
 MongoDB supports "compound indexes," where a single index structure
 holds references to multiple fields within a collection's
 documents. Consider the collection ``products`` that holds documents
-that resemble the following  example document:
+that resemble the following example document:
 
 .. code-block:: javascript
 
@@ -184,21 +184,24 @@ specify a single compound index to support both of these queries:
 
    db.products.ensureIndex( { "item": 1, "stock": 1 } )
 
+Note that that order of the fields in a compound index is very important.
+Intuitively, the index above contains references to the documents sorted by 
+``item``, and within each item, sorted by ``stock``.  
 MongoDB will be able to use this index to support queries that select
 the ``item`` field as well as those queries that select the ``item``
-field **and** the ``stock`` field. However, these indexes will not
-support queries that select *only* the ``stock`` field.
+field **and** the ``stock`` field. However, this index will not
+be useful for queries that select *only* the ``stock`` field.
 
 Ascending and Descending
 ````````````````````````
 
 Indexes store references to fields in either ascending or descending
-order. The order of keys often doesn't matter because MongoDB can
-transverse the index in either direction. However, in compound
-indexes, for some kinds of sort operations, it's useful to have the
-fields running in opposite order.
+order. For single-field indexes, the order of keys doesn't matter,
+because MongoDB can traverse the index in either direction. However, for 
+compound indexes, it is occasionally useful to have the fields running in 
+opposite order relative to each other.
 
-To specify an index with an ascending order, use the following form:
+To specify an index with a descending order, use the following form:
 
 .. code-block:: javascript
 
@@ -213,6 +216,9 @@ following:
    db.products.ensureIndex( { "field0": 1, "field1": -1 } )
 
 .. TODO understand the sort operations better.
+.. TODO Kevin's note: a good example here might be an index on 
+   {"username" : 1, "timestamp" : -1} which would be helpful for listing
+   event history (most recent first) for all users (alphabetically). 
 
 .. _index-types-multikey: