Merge pull request #1463 from evildmp/ticket_20877_work_in_progress

Many thanks to all involved in discussions, and in particular to Tim Graham for painstaking reviews.

docs/index.txt

@@ -233,6 +233,14 @@ regions:
 * :doc:`"Local flavor" <topics/localflavor>`
 * :doc:`Time zones </topics/i18n/timezones>`
 
+Performance and optimization
+============================
+
+There are a variety of techniques and tools that can help get your code running
+more efficiently - faster, and using fewer system resources.
+
+* :doc:`Performance and optimization overview <topics/performance>`
+
 Python compatibility
 ====================
 

docs/ref/utils.txt

@@ -495,8 +495,8 @@ Atom1Feed
 
     For cases like this, use the ``django.utils.functional.allow_lazy()``
     decorator. It modifies the function so that *if* it's called with a lazy
-    translation as the first argument, the function evaluation is delayed until it
-    needs to be converted to a string.
+    translation as one of its arguments, the function evaluation is delayed
+    until it needs to be converted to a string.
 
     For example::
 

docs/topics/cache.txt

@@ -1162,22 +1162,6 @@ Example::
 
 .. _`Cache-Control spec`: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9
 
-Other optimizations
-===================
-
-Django comes with a few other pieces of middleware that can help optimize your
-site's performance:
-
-* ``django.middleware.http.ConditionalGetMiddleware`` adds support for
-  modern browsers to conditionally GET responses based on the ``ETag``
-  and ``Last-Modified`` headers.
-
-* :class:`django.middleware.gzip.GZipMiddleware` compresses responses for all
-  modern browsers, saving bandwidth and transfer time. Be warned, however,
-  that compression techniques like ``GZipMiddleware`` are subject to attacks.
-  See the warning in :class:`~django.middleware.gzip.GZipMiddleware` for
-  details.
-
 Order of MIDDLEWARE_CLASSES
 ===========================
 

docs/topics/db/optimization.txt

@@ -88,7 +88,8 @@ of parentheses, but will call callables automatically, hiding the above
 distinction.
 
 Be careful with your own custom properties - it is up to you to implement
-caching.
+caching when required, for example using the
+:class:`~django.utils.functional.cached_property` decorator.
 
 Use the ``with`` template tag
 -----------------------------
@@ -111,10 +112,11 @@ For instance:
 * At the most basic level, use :ref:`filter and exclude <queryset-api>` to do
   filtering in the database.
 
-* Use :class:`F expressions <django.db.models.F>` to do filtering
-  against other fields within the same model.
+* Use :class:`F expressions <django.db.models.F>` to filter
+  based on other fields within the same model.
 
-* Use :doc:`annotate to do aggregation in the database </topics/db/aggregation>`.
+* Use :doc:`annotate to do aggregation in the database
+  </topics/db/aggregation>`.
 
 If these aren't enough to generate the SQL you need:
 
@@ -233,6 +235,8 @@ queryset``.
 
 But:
 
+.. _overuse_of_count_and_exists:
+
 Don't overuse ``count()`` and ``exists()``
 ------------------------------------------
 

docs/topics/index.txt

@@ -26,6 +26,7 @@ Introductions to all the key parts of Django you'll need to know:
    pagination
    python3
    security
+   performance
    serialization
    settings
    signals