Clarified migration references

docs/content_management/data_migration/exporting_data.md

@@ -56,10 +56,10 @@ Below you can see part of the output of the default [[= product_name =]] install
             name: ref__content__user_group__users
             type: content_id
         -
-            name: ref_location__user_group__users
+            name: ref__location__user_group__users
             type: location_id
         -
-            name: ref_path__user_group__users
+            name: ref__path__user_group__users
             type: path
 ```
 

docs/content_management/data_migration/managing_migrations.md

@@ -69,7 +69,7 @@
 Since some migrations generate object properties (like IDs) during their execution, which cannot be known in advance, references provide migrations with the ability to use previously created object properties in further migrations.
 They can be subsequently used by passing them in their desired place with `reference:` prefix.
 
-The example below creates a content item of type "folder", and stores its location path as `"ref_path__folder__media"`.
+The example below creates a content item of type "folder", and stores its location path as `"ref__path__folder__media"`.
 Then this reference is reused as part of a new role, as a limitation.
 
 ```yaml
@@ -100,10 +100,10 @@
             name: ref__content__folder__media
             type: content_id
         -
-            name: ref_location__folder__media
+            name: ref__location__folder__media
             type: location_id
         -
-            name: ref_path__folder__media
+            name: ref__path__folder__media
             type: path
 
 -
@@ -118,35 +118,40 @@
             limitations:
                 -
                     identifier: Subtree
-                    values: ['reference:ref_path__folder__media']
+                    values: ['reference:ref__path__folder__media']
 
 ```
 
-By default, reference files are located in a separate directory `src/Migrations/Ibexa/references` (for more information, see [previewing reference](#preview-configuration) `ibexa_migrations.migration_directory` and `ibexa_migrations.references_files_subdir` options).
+By default, references are stored in memory and can be reused within the same migration file without additional steps.
+
+To reuse them across different migration files, you can save them to disk.
+Reference files are located in a separate directory `src/Migrations/Ibexa/references` (for more information, see [previewing reference](#preview-configuration) `ibexa_migrations.migration_directory` and `ibexa_migrations.references_files_subdir` options).
 
 Reference files are **NOT** loaded by default. A separate step (type: "reference", mode: "load", with filename as "value") is required.
 Similarly, saving a reference file is done using type: "reference", mode: "save" step, with filename.
 
-For example:
+References must be loaded **before** they can be used in the same migration file. 
+The order of migration steps matters - they are executed sequentially from top to bottom.
 
 ```yaml
 -
     type: reference
     mode: load
-    filename: 'references.yaml'
+    filename: 'references/references.yaml' # Load references created by other migrations
 
+# Use them
+-
+    type: content
+    mode: create
+    # ...
+
+# Save any new references if needed
 -
     type: reference
     mode: save
-    # You can also use 'references.yaml', in this case it's overridden
-    filename: 'new_references.yaml'
+    filename: 'references/new_references.yaml'
 ```
 
-!!! note
-
-    You don't need to save references if they're used in the same migration file.
-    References are stored in memory during migration, whether they're used or not.
-
 ## Available reference types
 
 - `content`