Revises 8.x-8.x upgrade guide

[natasha-moore-elastic]

Contributes to #5302.

Revises the instructions for upgrading from an 8.x to an 8.x version. Mostly reuses the content from the 7.17 to 8.x upgrade guide, but without the 7.17-specific information.

[github-actions]

A documentation preview will be available soon.

• 🔨 Buildkite builds
• 📚 HTML diff
• 📙 Preview page

Request a new doc build by commenting

• Rebuild this PR: run docs-build
• Rebuild this PR and all Elastic docs: run docs-build rebuild

_{run docs-build is much faster than run docs-build rebuild. A rebuild should only be needed in rare situations.}

_{If your PR continues to fail for an unknown reason, the doc build pipeline may be broken. Elastic employees can check the pipeline status here.}

[joepeeples]

Just a few optional suggestions, so went ahead and approved in case you want to merge now. Ping again if you need re-approval!

[111andre111]

Looking to the rendered docs page https://security-docs_bk_5830.docs-preview.app.elstc.co/guide/en/security/master/upgrade-intro.html
I have a little general observations question.
We have these headers for upgrades of pre-8.x upgrades:


In comparison to that the 8.x to 8.x Upgrade has a completely other header size level. For me at least from a readability perspective that doesn't sound about right.

In my opinion, there there should be the same separate header level for that section and if there are overlapping sections, these could be linked together, like third step that needs to be done is x, see section <link to y>.

Please correct me if I am wrong.

[natasha-moore-elastic]

Looking to the rendered docs page https://security-docs_bk_5830.docs-preview.app.elstc.co/guide/en/security/master/upgrade-intro.html I have a little general observations question. We have these headers for upgrades of pre-8.x upgrades: In comparison to that the 8.x to 8.x Upgrade has a completely other header size level. For me at least from a readability perspective that doesn't sound about right. In my opinion, there there should be the same separate header level for that section and if there are overlapping sections, these could be linked together, like third step that needs to be done is x, see section <link to y>.

Please correct me if I am wrong.

Hi @111andre111, thanks for having a look. Perform an 8.x to 8.x upgrade on a deployment is a subsection within the Upgrade from an earlier 8.x version section, which is why the heading sizes are different. Both sections talk about the same kind of upgrade (8.x to 8.x)

Essentially, Upgrade from an earlier 8.x version consists of the following steps:

1. Plan for your upgrade
2. Pre-upgrade steps
3. Perform the upgrade

Maybe this would be clearer if we renamed Upgrade from an earlier 8.x version to Upgrade from an 8.x to an 8.x version. This would also be consistent with the other main section titles (Upgrade from 7.17 to an 8.x version and Upgrade from 7.16 or earlier to an 8.x version).