--- a/addon-sdk/source/doc/module-source/sdk/indexed-db.md
+++ b/addon-sdk/source/doc/module-source/sdk/indexed-db.md
@@ -32,20 +32,128 @@
       console.log("success");
     };
 
-This module also exports all the other objects that implement
-the IndexedDB API, listed below under
-[API Reference](modules/sdk/indexed-db.html#API Reference).
+Most of the objects that implement the IndexedDB API, such as
+[IDBTransaction](https://developer.mozilla.org/en-US/docs/IndexedDB/IDBTransaction),
+[IDBOpenDBRequest](https://developer.mozilla.org/en-US/docs/IndexedDB/IDBOpenDBRequest),
+and [IDBObjectStore](https://developer.mozilla.org/en-US/docs/IndexedDB/IDBObjectStore),
+are accessible through the indexedDB object itself.
 
 The API exposed by `indexed-db` is almost identical to the DOM IndexedDB API,
 so we haven't repeated its documentation here, but refer you to the
 [IndexedDB API documentation](https://developer.mozilla.org/en-US/docs/IndexedDB)
 for all the details.
 
-The database created will be unique and private per addon, and is not linked to any website database. The module cannot be used to interact with a given website database. See [bug 778197](https://bugzilla.mozilla.org/show_bug.cgi?id=779197) and [bug 786688](https://bugzilla.mozilla.org/show_bug.cgi?id=786688).
+The database created will be unique and private per add-on, and is not linked
+to any website database. The module cannot be used to interact with a given
+website database. See
+[bug 778197](https://bugzilla.mozilla.org/show_bug.cgi?id=779197) and
+[bug 786688](https://bugzilla.mozilla.org/show_bug.cgi?id=786688).
 
-## Example of Usage
+## Example
 
-[Promise-based example using indexedDB for record storage](https://github.com/gregglind/micropilot/blob/ec65446d611a65b0646be1806359c463193d5a91/lib/micropilot.js#L80-L198).
+Here's a complete add-on that adds two widgets to the browser: the widget labeled
+"Add" add the title of the current tab to a database, while the widget labeled
+"List" lists all the titles in the database.
+
+The add-on implements helper functions `open()`, `addItem()` and `getItems()`
+to open the database, add a new item to the database, and get all items in the
+database.
+
+    var { indexedDB, IDBKeyRange } = require('sdk/indexed-db');
+    var widgets = require("sdk/widget");
+
+    var database = {};
+
+    database.onerror = function(e) {
+      console.error(e.value)
+    }
+
+    function open(version) {
+      var request = indexedDB.open("stuff", version);
+
+      request.onupgradeneeded = function(e) {
+        var db = e.target.result;
+        e.target.transaction.onerror = database.onerror;
+
+        if(db.objectStoreNames.contains("items")) {
+          db.deleteObjectStore("items");
+        }
+
+        var store = db.createObjectStore("items",
+          {keyPath: "time"});
+      };
+
+      request.onsuccess = function(e) {
+        database.db = e.target.result;
+      };
+
+      request.onerror = database.onerror;
+    };
+
+    function addItem(name) {
+      var db = database.db;
+      var trans = db.transaction(["items"], "readwrite");
+      var store = trans.objectStore("items");
+      var time = new Date().getTime();
+      var request = store.put({
+        "name": name,
+        "time": time
+      });
+
+      request.onerror = database.onerror;
+    };
+
+    function getItems(callback) {
+      var cb = callback;
+      var db = database.db;
+      var trans = db.transaction(["items"], "readwrite");
+      var store = trans.objectStore("items");
+      var items = new Array();
+
+      trans.oncomplete = function() {
+        cb(items);
+      }
+
+      var keyRange = IDBKeyRange.lowerBound(0);
+      var cursorRequest = store.openCursor(keyRange);
+
+      cursorRequest.onsuccess = function(e) {
+        var result = e.target.result;
+        if(!!result == false)
+          return;
+
+        items.push(result.value.name);
+        result.continue();
+      };
+
+      cursorRequest.onerror = database.onerror;
+    };
+
+    function listItems(itemList) {
+      console.log(itemList);
+    }
+
+    open("1");
+
+    widgets.Widget({
+      id: "add-it",
+      width: 50,
+      label: "Add",
+      content: "Add",
+      onClick: function() {
+        addItem(require("sdk/tabs").activeTab.title);
+      }
+    });
+
+    widgets.Widget({
+      id: "list-them",
+      width: 50,
+      label: "List",
+      content: "List",
+      onClick: function() {
+        getItems(listItems);
+      }
+    });
 
 <api name="indexedDB">
 @property {object}
@@ -61,71 +169,6 @@
 See the [IDBKeyRange documentation](https://developer.mozilla.org/en-US/docs/IndexedDB/IDBKeyRange).
 </api>
 
-<api name="IDBCursor">
-@property {object}
-
-For traversing or iterating records in a database.
-See the [IDBCursor documentation](https://developer.mozilla.org/en-US/docs/IndexedDB/IDBCursor).
-
-</api>
-
-<api name="IDBTransaction">
-@property {object}
-
-Represents a database transaction.
-See the [IDBTransaction documentation](https://developer.mozilla.org/en-US/docs/IndexedDB/IDBTransaction).
-</api>
-
-<api name="IDBOpenDBRequest">
-@property {object}
-
-Represents an asynchronous request to open a database.
-See the [IDBOpenDBRequest documentation](https://developer.mozilla.org/en-US/docs/IndexedDB/IDBOpenDBRequest).
-</api>
-
-<api name="IDBVersionChangeEvent">
-@property {object}
-
-Event indicating that the database version has changed.
-See the [IDBVersionChangeEvent documentation](https://developer.mozilla.org/en-US/docs/IndexedDB/IDBVersionChangeEvent).
-</api>
-
-<api name="IDBDatabase">
-@property {object}
-
-Represents a connection to a database.
-See the [IDBDatabase documentation](https://developer.mozilla.org/en-US/docs/IndexedDB/IDBDatabase).
-</api>
-
-<api name="IDBFactory">
-@property {object}
-
-Enables you to create, open, and delete databases.
-See the [IDBFactory documentation](https://developer.mozilla.org/en-US/docs/IndexedDB/IDBFactory).
-</api>
-
-<api name="IDBIndex">
-@property {object}
-
-Provides access to a database index.
-See the [IDBIndex documentation](https://developer.mozilla.org/en-US/docs/IndexedDB/IDBIndex).
-</api>
-
-<api name="IDBObjectStore">
-@property {object}
-
-Represents an object store in a database.
-See the [IDBObjectStore documentation](https://developer.mozilla.org/en-US/docs/IndexedDB/IDBObjectStore).
-</api>
-
-<api name="IDBRequest">
-@property {object}
-
-Provides access to the results of asynchronous requests to databases
-and database objects.
-See the [IDBRequest documentation](https://developer.mozilla.org/en-US/docs/IndexedDB/IDBRequest).
-</api>
-
 <api name="DOMException">
 @property {object}