diff --git a/documentation/usage-filestate.md b/documentation/usage-filestate.md
index efb0f44..0d9df8e 100644
--- a/documentation/usage-filestate.md
+++ b/documentation/usage-filestate.md
@@ -68,6 +68,18 @@ struct LargeDataView: View {
 }
 ```
 
+### Migration Considerations
+
+When updating your data model, it's important to account for potential migration challenges, especially when working with persisted data using **StoredState**, **FileState**, or **SyncState**. Without proper migration handling, changes like adding new fields or modifying data formats can cause issues when older data is loaded.
+
+Here are some key points to keep in mind:
+- **Adding New Non-Optional Fields**: Ensure new fields are either optional or have default values to maintain backward compatibility.
+- **Handling Data Format Changes**: If the structure of your model changes, implement custom decoding logic to support old formats.
+- **Versioning Your Models**: Use a `version` field in your models to help with migrations and apply logic based on the data’s version.
+
+To learn more about how to manage migrations and avoid potential issues, refer to the [Migration Considerations Guide](migration-considerations.md).
+
+
 ## Best Practices
 
 - **Use for Large or Complex Data**: If you're storing large data or complex objects, `FileState` is ideal over `StoredState`.