[DRAFT] Implement alternate SM install journey

[conceptualshark]

Description

This PR attempts to implement a proposed restructuring of the initial/installation SM content. It does not attempt to rewrite any of this content, only attempt to change the architecture; changes to content can come in future iterations, and may be identified here for updates.

I expect there will be future changes required, but would like this to move iteratively, and can follow up with additional improvements to content as they are identified.

Current (left) vs Proposed (right) state of the docs:

Most importantly:

1. A "getting started" section has been created for local deployment options to live, removing them from being deeply nested in the setup docs.

2. The "Install" section brings manual and docker installations up to the same level as the helm install to better align with updates/support planned for these options.

3. The "Deploy" section has been brought up a level (previously nested within "Setup"), and now includes reference architecture. This is better positioned for the panned content update to use k8s/docker/etc landing pages, as opposed to platform (aws/gcp/etc) landing pages, and better reflects the expected engineering experience through the docs ("Deploy" here is not confused with modeler deployment options).

4. "Update" now includes both the Helm and generic update guides. Customers have been confused by where these changes live and the differences between these guides; internally, it has been difficult to know which to update. In the future, these distinctions should be made even clearer with a landing page.

5. "Configuration and deployment user guides" has been moved up to the side navigation (was buried in "Setup"), and renamed to "Configure" instead of the duplicated "Guides". This should also be updated in the future to reflect the content here is about configuration for production deployments, vs. "Operational guides" focus on items needed when you have a working production instance.

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]

👋 🤖 🤔 Hello, @conceptualshark! Did you make your changes in all the right places?

These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.6/.

• docs/self-managed/about-self-managed.md
• docs/self-managed/get-started/index.md
• docs/self-managed/setup/index.md
• docs/self-managed/setup/install.md
• docs/self-managed/setup/overview.md
• docs/self-managed/setup/upgrade.md
• docs/self-managed/update/index.md

These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.7/.

• docs/self-managed/about-self-managed.md
• docs/self-managed/get-started/index.md
• docs/self-managed/setup/index.md
• docs/self-managed/setup/install.md
• docs/self-managed/setup/overview.md
• docs/self-managed/setup/upgrade.md
• docs/self-managed/update/index.md

You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines.

[conceptualshark]

@theburi I don't think this represents the final state, just an initial cutover to a new structure before we introduce any content changes. Here's a few outstanding items:

• Right now, "Reference architecture" is nested under "Deploy," but I think these could be better merged as the content is updated.
• In the initial miro draft, "Deploy" was not recommended, but I still think it makes more sense for the user experience. Users in the SM docs are going to be looking for instructions on how to deploy a SM distribution; they may not recognize that there is any overlap with Deploying in Modeler, as their use cases are different. I think the audiences will be sufficiently different to know what they're looking for here, and Deploy is the most descriptive. We also currently use Deploy as a section under Setup, and haven't had any reported confusion there yet.
• I'd like to create a few more landing pages, likely in a follow-up PR: some summary content for getting started, update the installation landing page, a new/updated Deploy landing page, and one for Update to describe the difference between the two guides here (Helm vs not Helm).
• Nothing in operational guides, components, etc, is touched yet in this PR - only the initial install/onboarding experience.

[hisImminence]

Thanks @conceptualshark! As dsicussed - great first iteration to structure the docs in a more user journey focused way!

[Langleu]

🚀

[conceptualshark]

@akeller @theburi Looking for some final feedback here to ideally get a version of this merged prior to the next alpha/other, additional content restructuring. I don't plan on making significant changes to the actual written docs in this PR, but have created some landing pages for the new content sections to at least give a place for future content to live.

I presented this to the SM teams at our kick-off meeting, and received approval there for internal understanding, as well as for meeting the expectations of what our SM audience might expect for coming to this section of the docs.

I've hesitated on backporting to 8.7, but think it might be worthwhile if the upcoming reference architecture docs/changes are going to be available in 8.7 as well. Otherwise, the goal is to position these docs better for the 8.8 unified architecture, with suggestions for the remaining content to follow!

[akeller]

The high-level simplicity here is fab!

[akeller]

Is the manual option intentionally under reference arch? Can I get more context here?

[akeller]

I'm really happy with the direction this is heading and think you have a few choices. None of this is blocking if you are going to 8.8, but there are a few catches:

💡 You can merge, pretty much as-is, to 8.8. This would mean you accept that the rendered sidebar content doesn't reflect the directories in the repo, which could make it a weird experience to update and navigate, particularly if you look at the URLs. If you assume most people navigate this area through the sidebar, the URLs in an unreleased version may not matter as much. But as we approach 8.8, this would need to be cleaned up and there would be a healthy amount of redirects. This enables you to iterate but also deliver incrementally, which I fully support.

‼️ Landing pages will need more context/content, particularly the getting started area. We need to ensure people who drop in there but want general onboarding to Camunda can get to the other content. I'd also like to see a clear pointer to the C8Run experience and why someone would opt for the other. This helps set some expectations, including encouraging people to use C8Run first. Similarly, why would I update by helm vs. by version, etc.

❓ Backporting to 8.7 means things need to be really buttoned up by April. Is that reasonable? Particularly given my comments above. In the spirit of incremental delivery, and as the DRI of this docs area, please feel empowered to focus on 8.8 and bring that to a fantastic state in time for release day. That said, you'll likely still continue to get feedback about 8.7 docs.

[conceptualshark]

💡 You can merge, pretty much as-is, to 8.8. This would mean you accept that the rendered sidebar content doesn't reflect the directories in the repo, which could make it a weird experience to update and navigate, particularly if you look at the URLs. If you assume most people navigate this area through the sidebar, the URLs in an unreleased version may not matter as much. But as we approach 8.8, this would need to be cleaned up and there would be a healthy amount of redirects. This enables you to iterate but also deliver incrementally, which I fully support.

Based on some ongoing discussions I've had about additional content moves/restructuring for the actual Components, I'd like to make this whole rearchitecture an 8.8 goal and get the initial structure in place. This means I can follow up with additional landing page information, and eventually set up the redirects (do we do them for new branches? I am not sure if any links would break if /8.8/ doesn't exist yet).

[conceptualshark]

After speaking with @theburi, the suggestion was made to rename "Deploy" to just the base "Reference architecture." This moves the top-level Ref arch guides (Overview, Manual JAR) into the top-level here, and would most impact future updates to build out the one-stop pages for Kubernetes, etc, as those items would now live in this same section.

@hisImminence @Langleu @akeller Does this reflect how you would expect to find this information if you were attempting to install/deploy Camunda on your own? Is there any value to separate or nested Deploy vs Reference Arch sections? I think this user journey is a little less clear, but if this is how things usually look, I'm happy to leave it as-is.

[github-actions]

🚧 The preview environment for the commit 58537a3 is being built. This usually takes 15-20 minutes.

[hisImminence]

@hisImminence @Langleu @akeller Does this reflect how you would expect to find this information if you were attempting to install/deploy Camunda on your own? Is there any value to separate or nested Deploy vs Reference Arch sections? I think this user journey is a little less clear, but if this is how things usually look, I'm happy to leave it as-is.

I personally like the "action orientated" menu bar (install, deploy, update, configure) - I find it clear and easy.

"Reference architecture" seems to break that pattern. But as reference architecture seems to get a very prominent name (also used in blog posts, CamundaCon, etc. ...) - I guess thats the motivatino to put it more prominent on the top level. I would then suggest to keep it over install, so having:

• Getting Started
• Reference Architecture
• Install
• update
• Configure

This would still keep the action menu together and could be also seen as an order to go through (what makes sense imo): first getting started, then understand the architecture + infrastructure, then install the application, ...