Tidy up some of the transaction documentation.

docs/topics/db/transactions.txt

@@ -92,19 +92,15 @@ Django provides a single API to control database transactions.
 
 .. function:: atomic(using=None, savepoint=True)
 
-    This function creates an atomic block for writes to the database.
-    (Atomicity is the defining property of database transactions.)
+    Atomicity is the defining property of database transactions. ``atomic``
+    allows us to create a block of code within which the atomicity on the
+    database is guaranteed. If the block of code is successfully completed, the
+    changes are committed to the database. If there is an exception, the
+    changes are rolled back.
 
-    When the block completes successfully, the changes are committed to the
-    database. When it raises an exception, the changes are rolled back.
-
-    ``atomic`` can be nested. In this case, when an inner block completes
-    successfully, its effects can still be rolled back if an exception is
-    raised in the outer block at a later point.
-
-    ``atomic`` takes a ``using`` argument which should be the name of a
-    database. If this argument isn't provided, Django uses the ``"default"``
-    database.
+    ``atomic`` blocks can be nested. In this case, when an inner block
+    completes successfully, its effects can still be rolled back if an
+    exception is raised in the outer block at a later point.
 
     ``atomic`` is usable both as a `decorator`_::
 
@@ -137,24 +133,32 @@ Django provides a single API to control database transactions.
 
         @transaction.atomic
         def viewfunc(request):
-            do_stuff()
+            create_parent()
 
             try:
                 with transaction.atomic():
-                    do_stuff_that_could_fail()
+                    generate_relationships()
             except IntegrityError:
                 handle_exception()
 
-            do_more_stuff()
+            add_children()
 
-    In this example, even if ``do_stuff_that_could_fail()`` causes a database
+    In this example, even if ``generate_relationships()`` causes a database
     error by breaking an integrity constraint, you can execute queries in
-    ``do_more_stuff()``, and the changes from ``do_stuff()`` are still there.
+    ``add_children()``, and the changes from ``create_parent()`` are still
+    there. Note that any operations attempted in ``generate_relationships()``
+    will already have been rolled back safely when ``handle_exception()`` is
+    called, so the exception handler can also operate on the database if
+    necessary.
 
     In order to guarantee atomicity, ``atomic`` disables some APIs. Attempting
     to commit, roll back, or change the autocommit state of the database
     connection within an ``atomic`` block will raise an exception.
 
+    ``atomic`` takes a ``using`` argument which should be the name of a
+    database. If this argument isn't provided, Django uses the ``"default"``
+    database.
+
     Under the hood, Django's transaction management code:
 
     - opens a transaction when entering the outermost ``atomic`` block;
@@ -516,7 +520,7 @@ Transaction states
 
 The three functions described above relied on a concept called "transaction
 states". This mechanisme was deprecated in Django 1.6, but it's still
-available until Django 1.8..
+available until Django 1.8.
 
 At any time, each database connection is in one of these two states: