2 files changed, 28 insertions, 5 deletions
diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md
index 61c8e8d8..39e09aaa 100755
--- a/docs/api-guide/generic-views.md
+++ b/docs/api-guide/generic-views.md
@@ -84,10 +84,9 @@ The following attributes control the basic view behavior.
 
 The following attributes are used to control pagination when used with list views.
 
-* `paginate_by` - The size of pages to use with paginated data.  If set to `None` then pagination is turned off.  If unset this uses the same value as the `PAGINATE_BY` setting, which defaults to `None`.
-* `paginate_by_param` - The name of a query parameter, which can be used by the client to override the default page size to use for pagination.  If unset this uses the same value as the `PAGINATE_BY_PARAM` setting, which defaults to `None`.
-* `pagination_serializer_class` - The pagination serializer class to use when determining the style of paginated responses.  Defaults to the same value as the `DEFAULT_PAGINATION_SERIALIZER_CLASS` setting.
-* `page_kwarg` - The name of a URL kwarg or URL query parameter which can be used by the client to control which page is requested.  Defaults to `'page'`.
+* `pagination_class` - The pagination class that should be used when paginating list results. Defaults to the same value as the `DEFAULT_PAGINATION_CLASS` setting, which is `'rest_framework.pagination.PageNumberPagination'`.
+
+Note that usage of the `paginate_by`, `paginate_by_param` and `page_kwarg` attributes are now pending deprecation. The `pagination_serializer_class` attribute and `DEFAULT_PAGINATION_SERIALIZER_CLASS` setting have been removed completely. Pagination settings should instead be controlled by overriding a pagination class and setting any configuration attributes there. See the pagination documentation for more details.
 
 **Filtering**:
 
diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md
index 697ba38d..13bd57ae 100644
--- a/docs/api-guide/pagination.md
+++ b/docs/api-guide/pagination.md
@@ -208,6 +208,30 @@ Note that the `paginate_queryset` method may set state on the pagination instanc
 
 ## Example
 
+Suppose we want to replace the default pagination output style with a modified format that  includes the next and previous links under in a nested 'links' key. We could specify a custom pagination class like so:
+
+    class CustomPagination(pagination.PageNumberPagination):
+        def get_paginated_response(self, data):
+            return Response({
+                'links': {
+                   'next': self.get_next_link(),
+                   'previous': self.get_previous_link()
+                },
+                'count': self.page.paginator.count,
+                'results': data
+            })
+
+We'd then need to setup the custom class in our configuration:
+
+    REST_FRAMEWORK = {
+        'DEFAULT_PAGINATION_CLASS': 'my_project.apps.core.pagination.CustomPagination',
+        'PAGE_SIZE': 100
+    }
+
+Note that if you care about how the ordering of keys is displayed in responses in the browsable API you might choose to use an `OrderedDict` when constructing the body of paginated responses, but this is optional.
+
+## Header based pagination
+
 Let's modify the built-in `PageNumberPagination` style, so that instead of include the pagination links in the body of the response, we'll instead include a `Link` header, in a [similar style to the GitHub API][github-link-pagination].
 
     class LinkHeaderPagination(pagination.PageNumberPagination):
@@ -234,7 +258,7 @@ To have your custom pagination class be used by default, use the `DEFAULT_PAGINA
 
     REST_FRAMEWORK = {
         'DEFAULT_PAGINATION_CLASS': 'my_project.apps.core.pagination.LinkHeaderPagination',
-        'DEFAULT_PAGE_SIZE': 10
+        'PAGE_SIZE': 100
     }
 
 API responses for list endpoints will now include a `Link` header, instead of including the pagination links as part of the body of the response, for example: