Possibly a more drastic rewrite of docs #13

Comparing the previous documentation to other projects (especially
pytest, flask) I think I was trying to cover absolutely every
aspect, in as much detail as possible.  That seemed reasonable at
the time, because I'm familiar with the code.

Stepping back, it seems unapproachable in its sudden depth.  I'm
going to try another approach that walks through different options
as users might discover them.  That also means staying away from
"this is how DynamoDB works" as much as possible.  That can live in
a section in the future if it's something people want.

docs/index.rst

@@ -9,10 +9,10 @@ Features
 
 * Simple declarative modeling
 * Extensible type system, useful built-in types
-* Safe expression-based wire format
+* Secure expression-based wire format
 * Simple atomic operations
-* Diff-based saves
 * Expressive conditions
+* Diff-based saves
 
 Installation
 ============
@@ -29,24 +29,19 @@ First, define and bind our model:
 
     import uuid
 
-
     from bloop import (
-        Engine, Column, UUID, String,
-        GlobalSecondaryIndex, new_base)
-    Base = new_base()
+        Column, Engine, GlobalSecondaryIndex,
+        String, UUID, new_base)
 
 
-    class Account(Base):
-        class Meta:
-            read_units = 5
-            write_units = 2
+    class Account(new_base()):
         id = Column(UUID, hash_key=True)
         name = Column(String)
         email = Column(String)
         by_email = GlobalSecondaryIndex(hash_key='email')
 
     engine = Engine()
-    engine.bind(base=Base)
+    engine.bind(Account)
 
 Save an instance, load by key, and get the first query result:
 
@@ -91,21 +86,6 @@ Kick it up a notch with conditional operations:
     :hidden:
     :maxdepth: 3
 
-    user/declarative_modeling
-    user/modifying_objects
-    user/retrieving_objects
-    user/conditions
-    user/atomic
-    user/indexes
-    user/types
-    user/custom_types
-    user/configuration
-    user/debugging
-    user/patterns
-    dev/internals
-
-
-.. _tricky code: https://gist.github.com/numberoverzero/f0633e71a6b0f3f6132e
-.. _simpler code: https://gist.github.com/numberoverzero/94c939b4106e88b13e83
-.. _conditional saves: https://gist.github.com/numberoverzero/91f15c041a94b66e9365
-.. _atomic updates: https://gist.github.com/numberoverzero/cc004d93055cfa224569
+    user/01_define
+    user/02_mutate
+    user/03_query_scan

docs/user/01_define.rst

@@ -0,0 +1,136 @@
+Defining Models
+^^^^^^^^^^^^^^^
+
+To start, you'll need to create a base class that your models inherit from:
+
+.. code-block:: python
+
+    from bloop import new_base
+
+    BaseModel = new_base()
+
+Add some columns to your model.  You'll need at least a hash key:
+
+.. code-block:: python
+
+    from bloop import Column, DateTime, String, UUID
+
+
+    class User(BaseModel):
+        id = Column(UUID, hash_key=True)
+        email = Column(String)
+        created_on = Column(DateTime)
+
+Finally, bind the model to an Engine to create the table:
+
+.. code-block:: python
+
+    from bloop import Engine
+
+    engine = Engine()
+    engine.bind(User)
+
+========
+Metadata
+========
+
+You can customize how the table is created with an inner ``Meta`` class:
+
+.. code-block:: python
+
+    class Tweet(BaseModel):
+        class Meta:
+            table_name = "custom_table_name"
+            read_units = 1000
+            write_units = 300
+
+        user = Column(Integer, hash_key=True)
+        created = Column(DateTime, range_key=True)
+
+Available properties:
+
+**table_name**
+    | *(default is class name)*
+    | The table name in DynamoDB.
+**read_units**
+    | *(default is 1)*
+    | The provisioned read units for the table.
+**write_units**
+    | *(default is 1)*
+    | The provisioned write units for the table.
+
+=======
+Columns
+=======
+
+.. code-block:: python
+
+    Column(typedef, hash_key=False, range_key=False, name=None, **kwargs)
+
+**hash_key**
+
+-----
+Types
+-----
+
+Each ``Column`` must have a type.  The built-in types are::
+
+    String
+    UUID
+    DateTime
+    Float
+    Integer
+    Binary
+    Boolean
+    Set
+    List
+    TypedMap
+    Map
+
+Many types can be passed directly without instantiating.  These are equivalent:
+
+.. code-block:: python
+
+    Column(String)
+    Column(String())
+
+    Column(DateTime)
+    Column(DateTime(timezone="utc"))
+
+    Column(Float)
+    Column(Float())
+
+Set, List, and TypedMap require an inner type.  Bloop requires type information for List and Map because there isn't
+enough type information when loading values from DynamoDB to determine the type to use.
+
+.. code-block:: python
+
+    Column(Set(DateTime))
+    Column(Set(Integer))
+    Column(Set(Binary))
+
+    Column(List(Boolean))
+
+    Column(TypedMap(Integer))
+
+-----------------
+Hash & Range Keys
+-----------------
+
+Every model needs a hash key; you may optionally include a range key.  These are specified with the ``hash_key`` and
+``range_key`` kwargs:
+
+.. code-block:: python
+
+    id = Column(Integer, hash_key=True)
+
+-----
+Names
+-----
+
+DynamoDB includes column names when computing item sizes.  Instead of shortening ``created_on`` to ``c`` in the model,
+bloop exposes a ``name`` kwarg to map the model name to a different DynamoDB name:
+
+.. code-block:: python
+
+    created_on = Column(DateTime, name="c")

docs/user/02_mutate.rst

@@ -0,0 +1,4 @@
+Save and Delete Objects
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Create some stuff, delete some stuff.

docs/user/03_query_scan.rst

@@ -0,0 +1,2 @@
+Query and Scan
+^^^^^^^^^^^^^^