Reorganize the SM update guide

[conceptualshark]

Description

This has NOT yet been backported, to spare me reproducing any work that results of review. Looking for feedback on this new structure - review the 8.5 version of this page for comparison.

Goals here are to:

• condense the update guide information into tabs (to determine later if individual pages/organization with the other other update guides would be helpful)
• reorganize the content to flow more linearly in terms of requirement
• Add additional information and links to get users where they need to be earlier in the process

When should this change go live?

• This is a bug fix, security concern, or something that needs urgent release support.
• This is already available but undocumented and should be released within a week.
• This on a specific schedule and the assignee will coordinate a release with the DevEx team. (apply hold label or convert to draft PR)
• This is part of a scheduled alpha or minor. (apply alpha or minor label)
• There is no urgency with this change and can be released at any time.

PR Checklist

• My changes are for an already released minor and are in /versioned_docs directory.
• My changes are for the next minor and are in /docs directory (aka /next/).

• My changes require an Engineering review, and I've assigned the Engineering DRI or delegate.
• My changes require a technical writer review, and I've assigned @camunda/tech-writers as a reviewer.

[github-actions]

👋 🤖 ✅ Looks like the changes were ported across versions, nice job! 🎉

You can read more about the versioning within our docs in our documentation guidelines.

[akeller]

Since this is the /next/ version, you would want to include 8.6, right? Or is this just reorganizing the current content only?

[conceptualshark]

Reorg of the current only - I don't think we have any notes yet for what config changes will be required in 8.5 > 8.6.

[christinaausley]

I LOVE that you've tidied this up something significantly cleaner. This is a nitpick, but I try to shoot for ~150 characters for SEO purposes 👍

[christinaausley]

Is this a very strong recommendation, or can we just say "For a smooth upgrade experience, determine your Helm chart and Helm CLI versions prior to starting your upgrade."? I try to stray away from "we recommend" if it is a stronger command, if that makes sense? See this PR for some context.

[jessesimpson36]

Maybe another distribution team member might have other opinions, but I don't think we're that strict on helm CLI versions. I know from reading commits on helm that they haven't added any new features in the past year, so if someones on ubuntu and installed apt install helm and that version of helm isn't like, 3 years old, I wouldn't expect issues. But the notice could be there simply to let people know the helm versions we're testing with.

[akeller]

@conceptualshark, do you need us to take a second pass to review this PR? Can you clean up the conflicts?

[conceptualshark]

@akeller I'm curious if you think I should get an engineering review on this? 🤔 Otherwise I can make the recommended updates and backport!

[akeller]

@akeller I'm curious if you think I should get an engineering review on this? 🤔 Otherwise I can make the recommended updates and backport!

Yes, probably good to bring in someone from the Distribution team to review this PR @conceptualshark

[conceptualshark]

@jessesimpson36 Do you mind taking a look at this, or recommending someone to review? Reorganizing the Update guide to make it a little easier to follow, so ideally it will still make sense!

[jessesimpson36]

I believe I originally added the above section because I wanted customers to validate that their upgrade was successful, and when I'm testing upgrades, I often test by doing those steps. I'd hope to see this content again in another form, if not specified here.

Deploying a model covers scenarios where all the applications pods status report healthy, but maybe theres some communication issue between pods.

[conceptualshark]

Is this something that is useful to validate/test for every upgrade? Right now it's removed because it was only listed in the 8.1 -> 8.2 upgrade section, which is removed here because 8.1 is no longer supported. If a validation section would be useful in general, I can make another issue to add something to this guide for it.

[jessesimpson36]

I've given my thoughts. Overall I like the change, and find the tabs to be a less cluttered experience than the lengthy sidebar. I don't want you to change anything regarding my above comment, but just keep it in mind. (or adjust at your discretion).

[conceptualshark]

Ready for a final(?) review here - I've only backported to 8.5, as we don't use the same style for the guide prior to that version. I'm not sure if it would be worth updating 8.2 - 8.4 as part of this PR/in general.

[github-actions]

🧹 Preview environment for this PR has been torn down.

[akeller]

Ready for a final(?) review here - I've only backported to 8.5, as we don't use the same style for the guide prior to that version. I'm not sure if it would be worth updating 8.2 - 8.4 as part of this PR/in general.

Late to the party, but for backporting large changes like this, I usually recommend doing exactly what you did - current and next versions only. Smaller changes that are easier (or critical) to update can be backported to all supported versions.