3 files changed, 33 insertions, 19 deletions

diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt
index b8dc7ef9ca..da7b73caed 100644
--- a/docs/ref/contrib/sites.txt
+++ b/docs/ref/contrib/sites.txt
@@ -209,8 +209,8 @@ subscribing to LJWorld.com alerts." Same goes for the email's message body.
 
 Note that an even more flexible (but more heavyweight) way of doing this would
 be to use Django's template system. Assuming Lawrence.com and LJWorld.com have
-different template directories (:setting:`TEMPLATE_DIRS`), you could simply
-farm out to the template system like so::
+different template directories (:setting:`DIRS <TEMPLATES-DIRS>`), you could
+simply farm out to the template system like so::
 
     from django.core.mail import send_mail
     from django.template import loader, Context
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index ae387023e7..befc40cf9d 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -2422,6 +2422,11 @@ TEMPLATE_DIRS
 
 Default: ``()`` (Empty tuple)
 
+.. deprecated:: 1.8
+
+    Set the :setting:`DIRS <TEMPLATES-DIRS>` option of a ``DjangoTemplates``
+    backend instead.
+
 List of locations of the template source files searched by
 :class:`django.template.loaders.filesystem.Loader`, in search order.
 
diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt
index 7ab29ab276..01f3445114 100644
--- a/docs/ref/templates/api.txt
+++ b/docs/ref/templates/api.txt
@@ -620,21 +620,30 @@ specified as a **template directory**.
 
 Django searches for template directories in a number of places, depending on
 your template-loader settings (see "Loader types" below), but the most basic
-way of specifying template directories is by using the :setting:`TEMPLATE_DIRS`
-setting.
+way of specifying template directories is by using the :setting:`DIRS
+<TEMPLATES-DIRS>` option.
 
-The TEMPLATE_DIRS setting
-~~~~~~~~~~~~~~~~~~~~~~~~~
+The DIRS option
+~~~~~~~~~~~~~~~
+
+.. versionchanged:: 1.8
 
-Tell Django what your template directories are by using the
-:setting:`TEMPLATE_DIRS` setting in your settings file. This should be set to a
-list or tuple of strings that contain full paths to your template
-directory(ies). Example::
+    This value used to be defined by the ``TEMPLATE_DIRS`` setting.
 
-    TEMPLATE_DIRS = (
-        "/home/html/templates/lawrence.com",
-        "/home/html/templates/default",
-    )
+Tell Django what your template directories are by using the :setting:`DIRS
+<TEMPLATES-DIRS>` option in the :setting:`TEMPLATES` setting in your settings
+file. This should be set to a list of strings that contain full paths to your
+template directory(ies). Example::
+
+    TEMPLATES = [
+        {
+            'BACKEND': 'django.template.backends.django.DjangoTemplates',
+            'DIRS': [
+                '/home/html/templates/lawrence.com',
+                '/home/html/templates/default',
+            ],
+        },
+    ]
 
 Your templates can go anywhere you want, as long as the directories and
 templates are readable by the Web server. They can have any extension you want,
@@ -679,8 +688,8 @@ The Python API
        The ``dirs`` parameter was deprecated.
 
 For example, if you call ``get_template('story_detail.html')`` and have the
-above :setting:`TEMPLATE_DIRS` setting, here are the files Django will look for,
-in order:
+above :setting:`DIRS <TEMPLATES-DIRS>` option, here are the files Django will
+look for, in order:
 
 * ``/home/html/templates/lawrence.com/story_detail.html``
 * ``/home/html/templates/default/story_detail.html``
@@ -718,8 +727,8 @@ To load a template that's within a subdirectory, just use a slash, like so::
 
     get_template('news/story_detail.html')
 
-Using the same :setting:`TEMPLATE_DIRS` setting from above, this example
-``get_template()`` call will attempt to load the following templates:
+Using the same :setting:`DIRS <TEMPLATES-DIRS>` option from above, this
+example ``get_template()`` call will attempt to load the following templates:
 
 * ``/home/html/templates/lawrence.com/news/story_detail.html``
 * ``/home/html/templates/default/news/story_detail.html``
@@ -976,7 +985,7 @@ in :ref:`settings-without-django-settings-module`. Simply import the appropriate
 pieces of the templating system and then, *before* you call any of the
 templating functions, call :func:`django.conf.settings.configure()` with any
 settings you wish to specify. You might want to consider setting at least
-:setting:`TEMPLATE_DIRS` (if you're going to use template loaders),
+:setting:`DIRS <TEMPLATES-DIRS>` (if you're going to use template loaders),
 :setting:`DEFAULT_CHARSET` (although the default of ``utf-8`` is probably fine)
 and :setting:`TEMPLATE_DEBUG`. If you plan to use the :ttag:`url` template tag,
 you will also need to set the :setting:`ROOT_URLCONF` setting. All available