diff --git a/docs/issue_registry_index.md b/docs/issue_registry_index.md
index d3c46619..426d199e 100644
--- a/docs/issue_registry_index.md
+++ b/docs/issue_registry_index.md
@@ -36,6 +36,20 @@ ir.async_create_issue(
 )
 ```
 
+## Issue life cycle
+
+### Issue persistence
+
+An issue will be kept in the issue registry until it's removed by the integration that created it or by the user [fixing](#fixing-an-issue) it.
+
+The `is_persistent` flag controls if an issue should be shown to the user after a restart of Home Assistant:
+- If the `is_persistent` flag is set on the issue, the issue will be shown again to the user after a restart. Use this for issues that can only be detected when they occur (update failed, unknown service in automation).
+- If the `is_persistent` flag is not set on the issue, the issue will not be shown again to the user after a restart until it's created again by its integration. Use this for issues that can be checked for, like low disk space.
+
+### Ignored issues
+
+It's possible for the user to "ignore" issues. An ignored issue is ignored until it's explicitly deleted - either by the integration or by the user successfully walking through its [repair flow](#fixing-an-issue) - and then created again. Ignoring an issue takes effect across restarts of Home Assistant regardless of [issue persistence](#issue-persistence).
+
 ## Deleting an issue
 
 Integrations typically don't need to delete issues, but it may be useful in some cases.