Note on '.model' as default only, with 'serializer_class', and 'queryset' attributes prefered. Closes #1100

docs/api-guide/generic-views.md

@@ -69,7 +69,7 @@ The following attributes control the basic view behavior.
 
 **Shortcuts**:
 
-* `model` - This shortcut may be used instead of setting either (or both) of the `queryset`/`serializer_class` attributes, although using the explicit style is generally preferred.  If used instead of `serializer_class`, then then `DEFAULT_MODEL_SERIALIZER_CLASS` setting will determine the base serializer class.
+* `model` - This shortcut may be used instead of setting either (or both) of the `queryset`/`serializer_class` attributes, although using the explicit style is generally preferred.  If used instead of `serializer_class`, then then `DEFAULT_MODEL_SERIALIZER_CLASS` setting will determine the base serializer class.  Note that `model` is only ever used for generating a default queryset or serializer class - the `queryset` and `serializer_class` attributes are always preferred if provided.
 
 **Pagination**:
 

docs/topics/writable-nested-serializers.md

@@ -0,0 +1,47 @@
+> To save HTTP requests, it may be convenient to send related documents along with the request.
+>
+> — [JSON API specification for Ember Data][cite].
+
+# Writable nested serializers
+
+Although flat data structures serve to properly delineate between the individual entities in your service, there are cases where it may be more appropriate or convenient to use nested data structures.
+
+Nested data structures are easy enough to work with if they're read-only - simply nest your serializer classes and you're good to go.  However, there are a few more subtleties to using writable nested serializers, due to the dependancies between the various model instances, and the need to save or delete multiple instances in a single action.
+
+## One-to-many data structures 
+
+*Example of a **read-only** nested serializer.  Nothing complex to worry about here.*
+
+	class ToDoItemSerializer(serializers.ModelSerializer):
+	    class Meta:
+	        model = ToDoItem
+	        fields = ('text', 'is_completed')
+	
+	class ToDoListSerializer(serializers.ModelSerializer):
+	    items = ToDoItemSerializer(many=True, read_only=True)
+	
+	    class Meta:
+	        model = ToDoList
+	        fields = ('title', 'items')
+
+Some example output from our serializer.
+
+    {
+        'title': 'Leaving party preperations',
+        'items': {
+            {'text': 'Compile playlist', 'is_completed': True},
+            {'text': 'Send invites', 'is_completed': False},
+            {'text': 'Clean house', 'is_completed': False}            
+        }
+    }
+
+Let's take a look at updating our nested one-to-many data structure.
+
+### Validation errors
+
+### Adding and removing items
+
+### Making PATCH requests
+
+
+[cite]: http://jsonapi.org/format/#url-based-json-api