DOCS-169 edits and feedback from mikeo

Author: Sam Kleinman

aspiration/use-cases/cms-metadata-and-asset-management.txt

@@ -153,8 +153,6 @@ The most common operations inside of a CMS center on creating and
 editing content. Consider the following :py:meth:`<pymongo:pymongo.collection.Collection.insert>`
 operation:
 
-TODO figure out what role the nonce plays. mikeo
-
 .. code-block:: python
 
    db.cms.nodes.insert({
@@ -174,9 +172,11 @@ TODO figure out what role the nonce plays. mikeo
         })
 
 Once inserted, your application must have some way of preventing
-multiple concurrent updates. The schema uses the special
-``nonce`` field which makes it possible for the application to detect
-concurrent edits. Consider the following :py:meth:`update <pymongo:pymongo.collection.Collection.update>`
+multiple concurrent updates. The schema uses the special ``nonce``
+field to help detect concurrent edits. By using the ``nonce`` field in
+the query portion of the :py:meth:`update <pymongo:pymongo.collection.Collection.update>` 
+operation, the application will generate an error if there is an
+editing collision. Consider the following :py:meth:`update <pymongo:pymongo.collection.Collection.update>`
 
 .. code-block:: python
 

aspiration/use-cases/cms-storing-comments.txt

@@ -99,8 +99,6 @@ structure like the following:
        text: 'This is so bogus ... '
    }
 
-TODO changed full_slug order; talk to mikeo
-
 This structure:
 
 - adds a ``parent_id`` field that stores the contents of the ``_id``
@@ -113,6 +111,13 @@ This structure:
   information to make it easier to sort documents in a threaded
   discussion by date.
 
+.. warning::
+
+   MongoDB can only index :ref:`128 characters <limits-index-size>`
+   including field name and namespace (i.e. database name and
+   collection name.) This may become an issue when you create an index
+   of the ``full_slug`` field to support sorting.
+
 Operations
 ~~~~~~~~~~
 

aspiration/use-cases/ecommerce-inventory-management.txt

@@ -355,8 +355,6 @@ cleanup operation that finds inventory items that have ``carted``
 items and check that to ensure that they exist in a user's cart, and
 return them to available inventory if they do not.
 
-TODO talk to mikeo
-
 .. code-block:: python
 
    def cleanup_inventory(timeout):
@@ -372,7 +370,7 @@ TODO talk to mikeo
                      for carted_item in item['carted']
                      if carted_item['timestamp'] < threshold)
 
-           # Find any carts that are active and refresh the carted items
+           # First Pass: Find any carts that are active and refresh the carted items
            for cart in db.cart.find({ '_id': {'$in': carted.keys() }, 'status':'active'}):
                cart = carted[cart['_id']]
 
@@ -382,7 +380,7 @@ TODO talk to mikeo
                    { '$set': {'carted.$.timestamp': now } })
                del carted[cart['_id']]
 
-           # All the carted items left in the dict need to now be
+           # Second Pass: All the carted items left in the dict need to now be
            #    returned to inventory
            for cart_id, carted_item in carted.items():
                db.inventory.update(
@@ -392,6 +390,18 @@ TODO talk to mikeo
                    { '$inc': { 'qty': carted_item['qty'] },
                      '$pull': { 'carted': { 'cart_id': cart_id } } })
 
+TODO edit and polish the next paragraph.
+
+To summarize: This operation finds all "carted" items that have
+time stamps older than the threshold. Then, the process makes two
+passes over these items:
+
+#. Of the items with time stamps older than the threshold, if the cart
+   is still active, it resets the time stamp to maintain the carts.
+
+#. Of the stale items that remain in inactive carts, the operation
+   returns these items to the inventory.
+
 .. note::
 
    The function above is safe for use because it checks to ensure that
@@ -417,9 +427,19 @@ There are two drawbacks for using ``_id`` as a shard key:
 
   You can mitigate this effect by choosing a random value upon the
   creation of a cart, such as a hash (i.e. MD5 or SHA-1) of an
-  ObjectID, as the ``_id``.
+  ObjectID, as the ``_id``. The process for this operation would
+  resemble the following:
+
+  .. code-block:: python
+
+     import hashlib
+     import bson
+
+     cart_id = bson.ObjectId()
+     cart_id_hash = hashlib.md5(str(cart_id)).hexdigest()
 
-TODO insert code example for creating a hashed key in python. mikeo
+     cart = { "_id": cart_id, "cart_hash": cart_id_hash }
+     db.cart.insert(cart)
 
 - Cart expiration and inventory adjustment requires update operations
   and queries to broadcast to all shards when using ``_id`` as a shard

aspiration/use-cases/real-time-analytics-pre-aggregated-reports.txt

@@ -474,8 +474,6 @@ over the last day, with hour-level granularity:
 If you want a few days of hourly data, you can use a query in the
 following form:
 
-TODO talk to mikeo
-
 .. code-block:: pycon
 
    >>> db.stats.daily.find(
@@ -486,14 +484,6 @@ TODO talk to mikeo
    ...     { 'metadata.date': 1, 'hourly': 1 } },
    ...     sort=[('metadata.date', 1)])
 
-This query allows you to retrieve the date along with the data to
-protect the unlikely situation where you have a day where:
-
-- your application did not pre-allocate a document for that resource,
-  and
-
-- the resource in question receive no events, or requests.
-
 Indexing
 ````````