[DOCS] Update migration APIs docs (#83901) (#83966)

* Adds a shared note that the migration APIs are mainly intended for internal use by Kibana's Upgrade Assistant.
* Updates the feature migration API docs to use updated "migration" terminology.
* Removes some references to major versions from the deprecation API docs.

(cherry picked from commit e117812)

Author: jrodewig

docs/reference/migration/apis/deprecation.asciidoc

@@ -5,14 +5,11 @@
 <titleabbrev>Deprecation info</titleabbrev>
 ++++
 
-IMPORTANT: Use this API to check for deprecated configuration before performing
-a major version upgrade. You should run it on the last minor version of the
-major version you are upgrading from, as earlier minor versions may not include
-all deprecations.
+include::{es-repo-dir}/migration/apis/shared-migration-apis-tip.asciidoc[]
 
 The deprecation API is to be used to retrieve information about different
 cluster, node, and index level settings that use deprecated features that will
-be removed or changed in the next major version.
+be removed or changed in a future version.
 
 [[migration-api-request]]
 ==== {api-request-title}
@@ -118,7 +115,7 @@ issue.
 
 |=======
 |warning | You can upgrade directly, but you are using deprecated functionality
-which will not be available or behave differently in the next major version.
+which will not be available or behave differently in a future version.
 |critical | You cannot upgrade without fixing this problem.
 |=======
 

docs/reference/migration/apis/feature_upgrade.asciidoc renamed to docs/reference/migration/apis/feature-migration.asciidoc

@@ -1,35 +1,47 @@
 [role="xpack"]
-[[migration-api-feature-upgrade]]
-=== Feature Upgrade APIs
+[[feature-migration-api]]
+=== Feature migration APIs
 ++++
-<titleabbrev>Feature upgrade APIs</titleabbrev>
+<titleabbrev>Feature migration</titleabbrev>
 ++++
 
-IMPORTANT: Use this API to check for system features that need to be upgraded before
-a major version upgrade. You should run it on the last minor version of the
-major version you are upgrading from.
+include::{es-repo-dir}/migration/apis/shared-migration-apis-tip.asciidoc[]
 
-The feature upgrade APIs are to be used to retrieve information about system features
-that have to be upgraded before a cluster can be migrated to the next major version number,
-and to trigger an automated system upgrade that might potentially involve downtime for
-{es} system features.
+Version upgrades sometimes require changes to how features store configuration
+information and data in system indices. The feature migration APIs enable you to
+see what features require changes, initiate the automatic migration process, and
+check migration status.
 
-[[feature-upgrade-api-request]]
+Some functionality might be temporarily unavailable during the migration
+process.
+
+[[feature-migration-api-request]]
 ==== {api-request-title}
 
 `GET /migration/system_features`
 
-[[feature-upgrade-api-prereqs]]
+`POST /migration/system_features`
+
+[[feature-migration-api-prereqs]]
 ==== {api-prereq-title}
 
 * If the {es} {security-features} are enabled, you must have the `manage`
 <<privileges-list-cluster,cluster privilege>> to use this API.
 
-[[feature-upgrade-api-example]]
+[[feature-migration-api-desc]]
+==== {api-description-title}
+
+Submit a GET request to the `_migration/system_features` endpoint to see what
+features need to be migrated and the status of any migrations that are in
+progress.
+
+Submit a POST request to the endpoint to start the migration process.
+
+[[feature-migration-api-example]]
 ==== {api-examples-title}
 
-To see the list of system features needing upgrades, submit a GET request to the
-`_migration/system_features` endpoint:
+When you submit a GET request to the `_migration/system_features` endpoint, the
+response indicates the status of any features that need to be migrated.
 
 [source,console]
 --------------------------------------------------
@@ -120,10 +132,10 @@ Example response:
 --------------------------------------------------
 // TESTRESPONSE[s/"minimum_index_version" : "8.0.0"/"minimum_index_version" : $body.$_path/]
 
-This response tells us that Elasticsearch security needs its internal
-indices upgraded before we can upgrade the cluster to 8.0.
 
-To perform the required upgrade, submit a POST request to the same endpoint.
+When you submit a POST request to the `_migration/system_features` endpoint to
+start the migration process, the response indicates what features will be
+migrated.
 
 [source,console]
 --------------------------------------------------
@@ -138,13 +150,13 @@ Example response:
   "accepted" : true,
   "features" : [
     {
-      "feature_name" : "security"
+      "feature_name" : "security" <1>
     }
   ]
 }
 --------------------------------------------------
 // TESTRESPONSE[skip: can't actually upgrade system indices in these tests]
 
-This tells us that the security index is being upgraded. To check the
-overall status of the upgrade, call the endpoint with GET.
+<1> {es} security will be migrated before the cluster is upgraded.
 
+Subsequent GET requests will return the status of the migration process.

docs/reference/migration/apis/shared-migration-apis-tip.asciidoc

@@ -0,0 +1,4 @@
+TIP: These APIs are designed for indirect use by {kib}'s **Upgrade Assistant**.
+We strongly recommend you use the **Upgrade Assistant** to upgrade from
+{prev-major-last} to {version}. For upgrade instructions, refer to
+{stack-ref}/upgrading-elastic-stack.html[Upgrading to Elastic {version}].

docs/reference/migration/migration.asciidoc

@@ -2,9 +2,12 @@
 [[migration-api]]
 == Migration APIs
 
-The migration APIs simplify upgrading {xpack} indices from one version to another.
+The migration APIs power {kib}'s **Upgrade Assistant** feature.
+
+include::apis/shared-migration-apis-tip.asciidoc[]
 
 * <<migration-api-deprecation>>
+* <<feature-migration-api>>
 
 include::apis/deprecation.asciidoc[]
-include::apis/feature_upgrade.asciidoc[]
+include::apis/feature-migration.asciidoc[]

docs/reference/redirects.asciidoc

@@ -3,6 +3,11 @@
 
 The following pages have moved or been deleted.
 
+[role="exclude",id="migration-api-feature-upgrade"]
+=== Feature upgrade APIs
+
+Refer to <<feature-migration-api,Feature migration APIs>>.
+
 [role="exclude",id="java-clients"]
 === Java transport client and security