Clarified SeparateDatabaseAndState docs and added example of changing ManyToManyField.

Co-Authored-By: Mariusz Felisiak <felisiak.mariusz@gmail.com>
Co-Authored-By: Carlton Gibson <carlton.gibson@noumenal.es>
Co-Authored-By: René Fleschenberg <rene@fleschenberg.net>

1 files changed, 16 insertions, 4 deletions

diff --git a/docs/ref/migration-operations.txt b/docs/ref/migration-operations.txt
index 148ac95839..9723478032 100644
--- a/docs/ref/migration-operations.txt
+++ b/docs/ref/migration-operations.txt
@@ -419,12 +419,24 @@ if ``atomic=True`` is passed to the ``RunPython`` operation.
 
 .. class:: SeparateDatabaseAndState(database_operations=None, state_operations=None)
 
-A highly specialized operation that let you mix and match the database
+A highly specialized operation that lets you mix and match the database
 (schema-changing) and state (autodetector-powering) aspects of operations.
 
-It accepts two lists of operations, and when asked to apply state will use the
-state list, and when asked to apply changes to the database will use the database
-list. Do not use this operation unless you're very sure you know what you're doing.
+It accepts two lists of operations. When asked to apply state, it will use the
+``state_operations`` list (this is a generalized version of :class:`RunSQL`'s
+``state_operations`` argument). When asked to apply changes to the database, it
+will use the ``database_operations`` list.
+
+If the actual state of the database and Django's view of the state get out of
+sync, this can break the migration framework, even leading to data loss. It's
+worth exercising caution and checking your database and state operations
+carefully. You can use :djadmin:`sqlmigrate` and :djadmin:`dbshell` to check
+your database operations. You can use :djadmin:`makemigrations`, especially
+with :option:`--dry-run<makemigrations --dry-run>`, to check your state
+operations.
+
+For an example using ``SeparateDatabaseAndState``, see
+:ref:`changing-a-manytomanyfield-to-use-a-through-model`.
 
 .. _writing-your-own-migration-operation: