4 files changed, 27 insertions, 6 deletions
diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md
index c8ccb08b..c22d6d8b 100644
--- a/docs/api-guide/exceptions.md
+++ b/docs/api-guide/exceptions.md
@@ -8,7 +8,7 @@
 
 ## Exception handling in REST framework views
 
-REST framework's views handle various exceptions, and deal with returning appropriate error responses for you.
+REST framework's views handle various exceptions, and deal with returning appropriate error responses.
 
 The handled exceptions are:
 
@@ -16,9 +16,9 @@ The handled exceptions are:
 * Django's `Http404` exception.
 * Django's `PermissionDenied` exception.
 
-In each case, REST framework will return a response, rendering it to an appropriate content-type.
+In each case, REST framework will return a response with an appropriate status code and content-type.  The body of the response will include any additional details regarding the nature of the error.
 
-By default all error messages will include a key `details` in the body of the response, but other keys may also be included.
+By default all error responses will include a key `details` in the body of the response, but other keys may also be included.
 
 For example, the following request:
 
diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md
index be22eefe..e0f3583f 100644
--- a/docs/api-guide/permissions.md
+++ b/docs/api-guide/permissions.md
@@ -12,7 +12,7 @@ Permission checks are always run at the very start of the view, before any other
 
 ## How permissions are determined
 
-Permissions in REST framework are always defined as a list of permission classes.  Before running the main body of the view, each permission in the list is checked.
+Permissions in REST framework are always defined as a list of permission classes.  Before running the main body of the view each permission in the list is checked.
 
 If any permission check fails an `exceptions.PermissionDenied` exception will be raised, and the main body of the view will not run.
 
@@ -73,7 +73,18 @@ This permission is suitable if you want to your API to allow read permissions to
 
 ## DjangoModelPermissions
 
-This permission class ties into Django's standard `django.contrib.auth` model permissions.  When applied to a view that has a `.model` property, permission will only be granted if the user
+This permission class ties into Django's standard `django.contrib.auth` [model permissions][contribauth].  When applied to a view that has a `.model` property, authorization will only be granted if the user has the relevant model permissions assigned.
+
+* `POST` requests require the user to have the `add` permission on the model.
+* `PUT` and `PATCH` requests require the user to have the `change` permission on the model.
+* `DELETE` requests require the user to have the `delete` permission on the model.
+ 
+The default behaviour can also be overridden to support custom model permissions.  For example, you might want to include a `view` model permission for `GET` requests.
+
+To use custom model permissions, override `DjangoModelPermissions` and set the `.perms_map` property.  Refer to the source code for details.
+
+The `DjangoModelPermissions` class also supports object-level permissions.  Third-party authorization backends such as [django-guardian][guardian] should work just fine with `DjangoModelPermissions` without any custom configuration required.
+
 
 ## Custom permissions
 
@@ -84,4 +95,6 @@ The method should return `True` if the request should be granted access, and `Fa
 
 [cite]: https://developer.apple.com/library/mac/#documentation/security/Conceptual/AuthenticationAndAuthorizationGuide/Authorization/Authorization.html
 [authentication]: authentication.md
-[throttling]: throttling.md
-\ No newline at end of file
+[throttling]: throttling.md
+[contribauth]: https://docs.djangoproject.com/en/1.0/topics/auth/#permissions
+[guardian]: https://github.com/lukaszb/django-guardian
+\ No newline at end of file
diff --git a/docs/static/css/drf-styles.css b/docs/static/css/drf-styles.css
index a5f0b97a..7ad9d717 100644
--- a/docs/static/css/drf-styles.css
+++ b/docs/static/css/drf-styles.css
@@ -22,6 +22,13 @@ pre {
     display: block;
 }
 
+/* Header link to GitHub */
+.repo-link {
+    float: right;
+    margin-right: 10px;
+    margin-top: 7px;
+}
+
 /* GitHub 'Star' badge */
 body.index #main-content iframe {
     float: right;
diff --git a/docs/template.html b/docs/template.html
index f20aabac..936b6d93 100644
--- a/docs/template.html
+++ b/docs/template.html
@@ -21,6 +21,7 @@
     <div class="navbar navbar-inverse navbar-fixed-top">
       <div class="navbar-inner">
         <div class="container-fluid">
+            <a class="repo-link btn btn-primary btn-small" href="https://github.com/tomchristie/django-rest-framework/tree/restframework2">GitHub</a>
           <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
             <span class="icon-bar"></span>
             <span class="icon-bar"></span>