diff --git a/docs/patterns/appfactories.rst b/docs/patterns/appfactories.rst
index 3ef80b42..5eeff541 100644
--- a/docs/patterns/appfactories.rst
+++ b/docs/patterns/appfactories.rst
@@ -54,20 +54,38 @@ get access to the application with the config? Use
Here we look up the name of a template in the config.
-Extension objects are not initially bound to an application. Using
-``db.init_app``, the app gets configured for the extension. No
-application-specific state is stored on the extension object, so one extension
-object can be used for multiple apps. For more information about the design of
-extensions refer to :doc:`/extensiondev`.
+Factories & Extensions
+----------------------
-Your `model.py` might look like this when using `Flask-SQLAlchemy
-`_::
+It's preferable to create your extensions and app factories so that the
+extension object does not initially get bound to the application.
+
+Using `Flask-SQLAlchemy `_,
+as an example, you should **not** do::
+
+ def create_app(config_filename):
+ app = Flask(__name__)
+ app.config.from_pyfile(config_filename)
+
+ db = SQLAlchemy(app)
+
+But, rather, in model.py (or equivalent)::
- from flask.ext.sqlalchemy import SQLAlchemy
- # no app object passed! Instead we use use db.init_app in the factory.
db = SQLAlchemy()
+
+and in your application.py (or equivalent)::
+
+ def create_app(config_filename):
+ app = Flask(__name__)
+ app.config.from_pyfile(config_filename)
+
+ from yourapplication.model import db
+ db.init_app(app)
+
- # create some models
+Using this design pattern, no application-specific state is stored on the
+extension object, so one extension object can be used for multiple apps.
+For more information about the design of extensions refer to :doc:`/extensiondev`.
Using Applications
------------------