- add a note to baked documentation indicating it is not

really of general use.  This extension is there only
for those who really want it based on observed performance
characteristics.

Change-Id: I2f612f26fdef4ddbeb1158ab1b344fad7083b11c

diff --git a/doc/build/orm/extensions/baked.rst b/doc/build/orm/extensions/baked.rst
index 1dd875a86400c1abbc7c60a6ebec247eee7bcace..0fb8da5dfec50f599282313ca88dd9299ffd9023 100644 (file)
--- a/doc/build/orm/extensions/baked.rst
+++ b/doc/build/orm/extensions/baked.rst
@@ -25,9 +25,12 @@ the caching of the SQL calls and result sets themselves is available in
 
 .. note::
 
-    The :mod:`sqlalchemy.ext.baked` extension should be considered
-    **experimental** as of 1.0.0.  It provides a dramatically different system
-    of producing queries which has yet to be proven at scale.
+    The :mod:`sqlalchemy.ext.baked` extension is **not for beginners**.  Using
+    it correctly requires a good high level understanding of how SQLAlchemy, the
+    database driver, and the backend database interact with each other.  This
+    extension presents a very specific kind of optimization that is not ordinarily
+    needed.  As noted above, it **does not cache queries**, only the string
+    formulation of the SQL itself.
 
 Synopsis
 --------