Tweak to 3.0 relationship docs

docs/api-guide/relations.md

@@ -245,7 +245,7 @@ For example, the following serializer:
             fields = ('order', 'title')
 
     class AlbumSerializer(serializers.ModelSerializer):
-        tracks = TrackSerializer(many=True)
+        tracks = TrackSerializer(many=True, read_only=True)
 
         class Meta:
             model = Album
@@ -305,6 +305,16 @@ This custom field would then serialize to the following representation.
 
 # Further notes
 
+## The `queryset` argument
+
+The `queryset` argument is only ever required for *writable* relationship field, in which case it is used for performing the model instance lookup, that maps from the primitive user input, into a model instance.
+
+In version 2.x a serializer class could *sometimes* automatically determine the `queryset` argument *if* a `ModelSerializer` class was being used.
+
+This behavior is now replaced with *always* using an explicit `queryset` argument for writable relational fields.
+
+Doing so reduces the amount of hidden 'magic' that `ModelSerializer` provides, makes the behavior of the field more clear, and ensures that it is trivial to move between using the `ModelSerializer` shortcut, or using fully explicit `Serializer` classes.
+
 ## Reverse relations
 
 Note that reverse relationships are not automatically included by the `ModelSerializer` and `HyperlinkedModelSerializer` classes.  To include a reverse relationship, you must explicitly add it to the fields list.  For example:

rest_framework/relations.py

@@ -321,7 +321,9 @@ class ManyRelatedField(Field):
     The `ManyRelatedField` class is responsible for handling iterating through
     the values and passing each one to the child relationship.
 
-    You shouldn't need to be using this class directly yourself.
+    This class is treated as private API.
+    You shouldn't generally need to be using this class directly yourself,
+    and should instead simply set 'many=True' on the relationship.
     """
     initial = []
     default_empty_html = []