Describe redirections and the permanent argument

diff --git a/website/templates/documentation.txt b/website/templates/documentation.txt
index 31b313432aa3729c46d61033efed5dfc5b628663..81f93c1825fc5a08c23ba7569ac6cddc3962f329 100644 (file)
--- a/website/templates/documentation.txt
+++ b/website/templates/documentation.txt
@@ -205,6 +205,23 @@ Other methods designed for overriding include:
  * `get_template_path(self)` - returns location of template files (default is
    in `Application` settings)
 
+### Redirection
+
+You can use `self.redirect` within a
+`RequestHandler` to redirect users elsewhere. 
+There is also an optional 
+parameter `permanent` which you can use to indicate
+that the redirection is considered permanent.  
+
+This triggers a `301 Moved Permanently` 
+HTTP status, which is useful for e.g.
+redirecting to a canonical URL for a page in an SEO-friendly manner.
+
+The default value of `permanent` is `False`, which is apt for things like redirecting
+users on successful POST requests.
+
+       self.redirect('/some-canonical-page', permanent=True)
+
 ### Templates
 
 You can use any template language supported by Python, but Tornado ships