diff --git a/docs/en/install-upgrade/index.asciidoc b/docs/en/install-upgrade/index.asciidoc
index af68eb0ca..ed577fbd9 100644
--- a/docs/en/install-upgrade/index.asciidoc
+++ b/docs/en/install-upgrade/index.asciidoc
@@ -5,7 +5,7 @@
 :kib-repo-dir:       {docdir}/../../../../kibana/docs
 
 include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
-include::{es-repo-dir}/Versions.asciidoc[]
+include::{asciidoc-dir}/../../shared/versions.asciidoc[]
 
 include::overview.asciidoc[]
 
diff --git a/docs/en/install-upgrade/upgrading-stack.asciidoc b/docs/en/install-upgrade/upgrading-stack.asciidoc
index 2a44604f7..89056aa72 100644
--- a/docs/en/install-upgrade/upgrading-stack.asciidoc
+++ b/docs/en/install-upgrade/upgrading-stack.asciidoc
@@ -215,45 +215,57 @@ modifications to the document data and metadata during reindexing.
 index as alias for the new index and delete the 2.x index.
 
 [[upgrade-internal-indices]]
-==== Upgrading internal indices for {major-version}
-
-The format used for the internal indices used by Kibana and {xpack} has
-changed in {major-version}. Before you can run Kibana and {xpack} in {version},
-these indices must be upgraded to the new format. If you are upgrading from a
-version prior to 5.6, you must upgrade them after after installing
-Elasticsearch {version}.
-
-To get a list of the indices that need to be upgraded, install {xpack} and use
-the {ref}/migration-api-assistance.html[`_migration/assistance` API]:
-
-[source,json]
+=== Upgrading internal indices for {major-version}
+
+{es} can read indices that were created in the *previous major version*. Older
+indices must be reindexed or deleted. For example, {es} {major-version} can use
+indices created in {es} {prev-major-version}, but not those created in earlier
+versions. This restriction also applies to the internal indices that are used by
+Kibana and the {xpack} features. Therefore, before you can use Kibana and
+{xpack} features in {version}, you must ensure the internal indices have a
+compatible index structure.
+
+If you are upgrading from a version prior to {prev-major-version}, you must
+upgrade to the most recent version of {prev-major-version} first. Then you can
+use the {kibana-ref}/upgrade-assistant.html[{kib} Upgrade Assistant] or the
+{ref}/docs-reindex.html[reindex API] to reindex the internal indices. For more
+information, see {ref}/reindex-upgrade.html[Reindex before upgrading].
+
+[TIP]
+====
+If you use {stack} {security-features}, before you reindex `.security*` internal
+indices it is a good idea to create a temporary superuser account in the `file`
+realm.
+
+. On a single node, add a temporary superuser account to the `file` realm. For
+example, run the {ref}/users-command.html[elasticsearch-users useradd] command:
++
+--
+[source,sh]
 ----------------------------------------------------------
-GET /_migration/assistance
+bin/elasticsearch-users useradd <user_name> \
+-p <password> -r superuser
 ----------------------------------------------------------
-// CONSOLE
+--
 
-To upgrade the `.security` index:
+. Use these credentials when you reindex the `.security*` index. That is to say,
+use them to log into {kib} and run the Upgrade Assistant or to call the
+reindex API. You can use your regular administration credentials to
+reindex the other internal indices.
 
-. On a single node, add a temporary superuser account to the `file` realm.
-. Use the {ref}/migration-api-upgrade.html[`_migration/upgrade`]
-API to upgrade the security index, submitting the request with the credentials
-for the temporary superuser:
+. Delete the temporary superuser account from the file realm. For
+example, run the {ref}/users-command.html[elasticsearch-users userdel] command:
 +
 --
-[source,json]
+[source,sh]
 ----------------------------------------------------------
-POST /_migration/upgrade/.security
+bin/elasticsearch-users userdel <user_name>
 ----------------------------------------------------------
-// CONSOLE
 --
 
-. Delete the temporary superuser account from the file realm.
-
-You can use your regular administration credentials to upgrade the other
-internal indices using the `_migration/upgrade` API.
-
-TIP: Once you upgrade the `.kibana` index, you can run Kibana and use the
-{xpack} Reindex Helper UI to upgrade the other indices.
+For more information, see
+{ref}/configuring-file-realm.html[Configuring a file realm].
+====
 
 [[upgrade-elastic-stack-for-elastic-cloud]]
 === Upgrading on Elastic Cloud