diff --git a/docs/config_entries_config_flow_handler.md b/docs/config_entries_config_flow_handler.md
index 291e4af7..796c2aa1 100644
--- a/docs/config_entries_config_flow_handler.md
+++ b/docs/config_entries_config_flow_handler.md
@@ -242,31 +242,9 @@ async def async_migrate_entry(hass, config_entry: ConfigEntry):
             # TODO: modify Config Entry data with changes in version 1.3
             pass
 
-        config_entry.version = 1
-        config_entry.minor_version = 3
-        hass.config_entries.async_update_entry(config_entry, data=new)
+        hass.config_entries.async_update_entry(config_entry, data=new, minor_version=3, version=1)
 
-    _LOGGER.debug("Migration to version %s successful", config_entry.version)
-
-    return True
-```
-
-If only the config entry version is changed, but no other properties, `async_update_entry` should not be called:
-```python
-# Example migration function which does not modify config entry properties, e.g. data or options
-async def async_migrate_entry(hass, config_entry: ConfigEntry):
-    """Migrate old entry."""
-    _LOGGER.debug("Migrating from version %s", config_entry.version)
-
-    if config_entry.version == 1:
-
-        # TODO: Do some changes which is not stored in the config entry itself
-
-        # There's no need to call async_update_entry, the config entry will automatically be
-        # saved when async_migrate_entry returns True
-        config_entry.version = 2
-
-    _LOGGER.debug("Migration to version %s successful", config_entry.version)
+    _LOGGER.debug("Migration to version %s.%s successful", config_entry.version, config_entry.minor_version)
 
     return True
 ```
diff --git a/docs/config_entries_index.md b/docs/config_entries_index.md
index 8e34d634..cc867ea8 100644
--- a/docs/config_entries_index.md
+++ b/docs/config_entries_index.md
@@ -150,3 +150,7 @@ If the config entry version is changed, `async_migrate_entry` must be implemente
 async def async_migrate_entry(hass: HomeAssistant, config_entry: ConfigEntry) -> bool:
     """Migrate old entry."""
 ```
+
+## Modifying a config entry
+
+A `ConfigEntry` object, including the data and options, must never be mutated directly by integrations, instead integrations must call `async_update_entry`, the use of which is illustrated in the [config flow documentation](/config_entries_config_flow_handler.md#config-entry-migration).