[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, @akeller! 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.7/.

• docs/self-managed/about-self-managed.md
• docs/self-managed/get-started/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]

🚀

[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, ...

[akeller]

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).

You do not need redirects for new branches.

[Langleu]

Sorry for only coming back to you on this now @conceptualshark.

Since the restructure won't happen on 8.7 but reference architecture will, you may be in the unique position to get user feedback throughout the release to tie it up for 8.8 to your liking. Might be against other peoples wishes but customer is king.

I don't have either preference, and from my pov in theory, both can live alongside. Neither is mutually exclusive.
E.g. at GitLab Reference architecture is a subsection of installation as it's subview of what installation is. Reference Arch is a more opinionated installation view than the generalized approach.

The only thing that I'd like to try to avoid is the following:
If you have a topic that is a page in itself but also a folder. Personally found it bad UX and you can easily miss the page as an enduser and makes you question the whole docs.

If you just click on the arrows to navigate you will miss the page and once you notice that it exists, OCD kicks in and makes you wonder what else you missed out on.

[akeller]

@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.

In the context of onboarding with Camunda, we have the Spring guide + C8Run, but in the SM docs we have a more verbose C8Run install and the local Kubernetes cluster setup. I would like some more context on the overview page about why these two options exist and a link to the Spring guide + C8Run if someone lands here and isn't intentionally trying to dive deep into the SM experience.

On the C8Run page, I would again ask for some context about this guide compared to the Spring guide + C8Run.

I would also like to see more limitations or what cannot be tested/explored with C8Run. This could be as simple as a "Limitations" section at the bottom of the page. Or, if we know specific new and exciting features won't work with C8Run, we can add that as a temporary admonition.

I love that all the Install options are production. I do worry that removing the Docker compose option and only having Docker images for Linux may be confusing. Can we guide users to the more suitable option for Windows? I see we repeat several times across the SM docs that Windows/MacOS are not supported for production, but I find myself wondering if we need to say "why". Was Docker compose intentionally removed? Is it part of the "Get started" section?

I like that the Reference architecture section is more conceptual, but still highly technical. I also like that we don't classify these as guides because they aren't step-by-step content. I don't miss the "deploy" section, but if we still want to use that keyword, we can add it to metadata.

@conceptualshark this may be way more than you were asking, but I tried to take a step back and think about the overall journey through the sidebar and pages. If you need to pull this feedback into other issues or PRs, please do so. It doesn't all need to be addressed here if this isn't within scope of the PR.

[theburi]

Hi. I'd like to see one change to this plan:
Deploy should be replaced with Reference Architecture. We will essentially move all content from the old Deploy sections to the Reference Architecture.

[akeller]

I think I've updated the branch successfully 🚀

In my next commit I'll tackle @theburi's feedback and anything else that needs to be cleaned up based on the responses above.

[github-actions]

[prettier] _{reported by reviewdog 🐶}

Suggested change

	--ifm-heading-font-family: IBM Plex Sans, -apple-system, blinkmacsystemfont,
	Segoe UI, roboto, oxygen-sans, ubuntu, cantarell, Helvetica Neue, sans-serif;
	--ifm-heading-font-family:
	IBM Plex Sans, -apple-system, blinkmacsystemfont, Segoe UI, roboto,
	oxygen-sans, ubuntu, cantarell, Helvetica Neue, sans-serif;

[github-actions]

The preview environment relating to the commit 7e1b5a5 has successfully been deployed. You can access it at https://preview.docs.camunda.cloud/pr-4601/

[akeller]

Since this is a pretty old PR (pre-8.7 release), I got it building, but I'm not happy with the changes I would need to make and content I would need to consolidate to get this PR in good standing. I'm going to create a new one and try to map the changes in the spirit of this PR.

@theburi please have a look at the current 8.8 docs. We already have a "Reference Architecture" section. If I rename "Deploy," we'll need to immediately figure out how to consolidate the info in the current Reference Architecture and Deploy sections.

☝️ Today's 8.8 SM sidebar

☝️ Current Deploy section

For example, the last screenshot with "Troubleshooting IAM Roles for Service Accounts (IRSA)" doesn't seem like it would fit into the "Reference Architecture" section.

[akeller]

#5768 for a (soon-to-be) mergeable PR.