DOCS-201 inital structural edit pass

Author: Sam Kleinman

draft/index.txt

@@ -63,7 +63,6 @@ Signposts
    :maxdepth: 2
 
    sharding
-   use-cases
 
 Reference
 ~~~~~~~~~

draft/use-cases/ad-campaign-management.txt

@@ -137,8 +137,8 @@ Query
 
 TODO: describe query
 
-Index Support
-`````````````
+Indexing
+````````
 
 TODO: describe indexes to optimize this query
 

draft/use-cases/ad-serving-ads.txt

@@ -1,5 +1,3 @@
-.. -*- rst -*-
-
 ==============================
 Online Advertising: Ad Serving
 ==============================
@@ -35,15 +33,17 @@ The examples that follow use the Python programming language and the
 :api:`PyMongo <python/current>` :term:`driver` for MongoDB, but you
 can implement this system using any language you choose.
 
-Design 1: Basic Ad Serving
---------------------------
+Serving Basic Ads
+-----------------
 
-A basic ad serving algorithm consists of the following steps:
+A basic ad serving algorithm consists of the following The:
 
-#. The network receives a request for an ad, specifying at a minimum the
+#. steps network receives a request for an ad, specifying at a minimum the
    ``site_id`` and ``zone_id`` to be served.
+
 #. The network consults its inventory of ads available to display and chooses an
    ad based on various business rules.
+
 #. The network returns the actual ad to be displayed, possibly recording the
    decision made as well.
 
@@ -52,8 +52,8 @@ as well as information stored in the ad inventory collection, to make the ad
 targeting decisions. Later examples will build on this, allowing more advanced ad
 targeting.
 
-Schema Design
-~~~~~~~~~~~~~
+Schema
+~~~~~~
 
 A very basic schema for storing ads available to be served consists of a single
 collection, ``ad.zone``:
@@ -83,6 +83,9 @@ ads, sorted by their ``ecpm`` values.
 Choosing an Ad to Serve
 ~~~~~~~~~~~~~~~~~~~~~~~
 
+Querying
+````````
+
 The query you'll use to choose which ad to serve selects a compatible ad and
 sorts by the advertiser's ``ecpm`` bid in order to maximize the ad network's
 profits:
@@ -101,8 +104,8 @@ profits:
        ecpm, ad_group = ecpm_groups.next()
        return choice(list(ad_group))
 
-Index Support
-`````````````
+Indexing
+````````
 
 In order to execute the ad choice with the lowest latency possible, you'll want
 to have a compound index on (``site_id``, ``zone_id``):
@@ -116,6 +119,9 @@ to have a compound index on (``site_id``, ``zone_id``):
 Making an Ad Campaign Inactive
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Updating
+````````
+
 One case you'll have to deal with in this solution making a campaign
 inactive. This may happen for a variety of reasons. For instance, the campaign
 may have reached its end date or exhausted its budget for the current time
@@ -133,8 +139,8 @@ The update statement above first selects only those ad zones which had avaialabl
 ads from the given ``campaign_id`` and then uses the ``$pull`` modifier to remove
 them from rotation.
 
-Index Support
-`````````````
+Indexing
+````````
 
 In order to execute the multi-update quickly, you should maintain an index on the
 ``ads.campaign_id`` field:
@@ -158,8 +164,8 @@ good approach is to shard on the (``site_id``, ``zone_id``) combination:
    ...     'key': {'site_id': 1, 'zone_id': 1} })
    { "collectionsharded": "ad.zone", "ok": 1 }
 
-Design 2: Adding Frequency Capping
-----------------------------------
+Adding Frequency Capping
+------------------------
 
 One problem with the logic described in Design 1 above is that it will tend to
 display the same ad over and over again until the campaign's budget is
@@ -174,8 +180,8 @@ transmitted to the ad network when logging impressions, clicks, conversions,
 etc., as well as the ad serving decision. This section focuses on how that
 profile data impacts the ad serving decision.
 
-Schema Design
-~~~~~~~~~~~~~
+Schema
+~~~~~~
 
 In order to use the user profile data, you need to store it. In this case, it's
 stored in a collection ``ad.user``:
@@ -210,17 +216,22 @@ There are a few things to note about the user profile:
 - Profile information is segmented by advertiser. Typically advertising data is
   sensitive competitive infomration that can't be shared among advertisers, so
   this must be kept separate.
+
 - All data is embedded in a single profile document. When you need to query this
   data (detailed below), you don't necessarily know which advertiser's ads you'll
   be showing, so it's a good practice to embed all advertisers in a single
   document.
+
 - The event information is grouped by event type within an advertiser, and sorted
   by timestamp. This allows rapid lookups of a stream of a particular type of
   event.
 
 Choosing an Ad to Serve
 ~~~~~~~~~~~~~~~~~~~~~~~
 
+Querying
+````````
+
 The query you'll use to choose which ad to serve now needs to iterate through
 ads in order of desireability and select the "best" ad that also satisfies the
 advertiser's targeting rules (in this case, the frequency cap):
@@ -275,8 +286,8 @@ stored in the user profile, from most recent to oldest, within a certain
 appears in the mipression stream, the ad is rejected. Otherwise it is acceptable
 and can be shown to the user.
 
-Index Support
-`````````````
+Indexing
+````````
 
 In order to retrieve the user profile with the lowest latency possible, there
 needs to be an index on the ``_id`` field, which MongoDB supplies by default.
@@ -293,8 +304,8 @@ When sharding the ``ad.user`` collection, choosing the ``_id`` field as a
    ...     'key': {'_id': 1 } })
    { "collectionsharded": "ad.user", "ok": 1 }
 
-Design 3: Keyword Targeting
----------------------------
+Keyword Targeting
+-----------------
 
 Where frequency capping above is an example of user profile targeting, you may
 also wish to perform content targeting so that the user receives relevant ads for
@@ -303,9 +314,8 @@ at the result of a search query. In this case, a list of ``keywords`` is sent to
 the ``choose_ad()`` call along with the ``site_id``, ``zone_id``, and
 ``user_id``.
 
-
-Schema Design
-~~~~~~~~~~~~~
+Schema
+~~~~~~
 
 In order to choose relevant ads, you'll need to expand the ``ad.zone`` collection
 to store keywords for each ad: