Clarified deconstruct() in Custom Model Field docs.

1 files changed, 8 insertions, 5 deletions

diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt
index 0a9aab4706..4bb81611cd 100644
--- a/docs/howto/custom-model-fields.txt
+++ b/docs/howto/custom-model-fields.txt
@@ -231,9 +231,10 @@ Field deconstruction
 --------------------
 
 The counterpoint to writing your ``__init__()`` method is writing the
-``deconstruct()`` method. This method tells Django how to take an instance
-of your new field and reduce it to a serialized form - in particular, what
-arguments to pass to ``__init__()`` to re-create it.
+:meth:`~.Field.deconstruct` method. It's used during :doc:`model migrations
+</topics/migrations>` to tell Django how to take an instance of your new field
+and reduce it to a serialized form - in particular, what arguments to pass to
+``__init__()`` to re-create it.
 
 If you haven't added any extra options on top of the field you inherited from,
 then there's no need to write a new ``deconstruct()`` method. If, however,
@@ -269,8 +270,10 @@ we can drop it from the keyword arguments for readability::
             del kwargs["max_length"]
             return name, path, args, kwargs
 
-If you add a new keyword argument, you need to write code to put its value
-into ``kwargs`` yourself::
+If you add a new keyword argument, you need to write code in ``deconstruct()``
+that puts its value into ``kwargs`` yourself. You should also omit the value
+from ``kwargs`` when it isn't necessary to reconstruct the state of the field,
+such as when the default value is being used::
 
     from django.db import models