Quickstart Narrative

[jeffmccune]

Update the quickstart guide based on feedback from Greg.

1. Grab the reader at the top.
2. Address "I'm not getting the story."
3. Tell a story similar to how the Change a Service guide tells a story.

Halfway down the page you get to the problem you're trying to solve -- "Before Holos we used Helm, Kustomize, and scripts to glue together all of the software that goes into a platform." This is the meat. It could be a lot stronger, though.

By this point, you've introduced the concept of a hypothetical software platform with an associated organization structure, but the only thing you're using that for is so the naming conventions in your examples make sense. Use them to tell the story. What problems is this typical banking platform facing?

[glarizza]

It's not clear to me whether or not ArgoCD is part of the platform, or just an example of a 3rd party piece of software that Holos can manage. If it's the latter, consider changing "Configure ArgoCD" to "Configure your first Component" and then explain that you're using ArgoCD as an example.

@jeffmccune In the quickstart you introduce ArgoCD, but switch to the cert-manager component when showing the root and leaf files. Was that because cert-manager is simpler than ArgoCD so there was less in the files to distract new users? I somewhat sympathize with the ArgoCD-related feedback above and think if we stick with it through to the end it would provide more continuity between the sections. If your initial concern was regarding the platform root file having a lot of additional complexity, then I think we can get away with only showing a portion of the file for the quickstart so we can emphasize the parts of Holos we care about.

[jeffmccune]

In the quickstart you introduce ArgoCD, but switch to the cert-manager component when showing the root and leaf files. Was that because cert-manager is simpler than ArgoCD so there was less in the files to distract new users?

Sort of. ArgoCD is a special case because there are two different aspects:

1. The ArgoCD component, just another component that manages a piece of software.
2. The Application resources. These are special, the platform team defines a configuration struct that allows all other teams to enable the automatic generation of an Application resource along with their component's manifest.

So what we switch from is configuring the Application resources to showing an example of a typical component. They're two very different things and aspects of Holos.

Regarding your empathy for the reader being confused. Could you clarify this to something like, "Configure GitOps". "Configure your first Component" isn't correct because we're not configuring a component yet, we're configuring all of the Application resources that go along with all of the components.

Feedback from Nate was positive regarding configuring GitOps, it's a good example of how a single one line boolean flag can affect the whole platform. And it's clearly visible in the rendered files.

Alternatively, maybe we swap the Render a Component and the Configure ArgoCD section as well?

[glarizza]

Ahh okay, one of the first things we show is how the simple change we make (RepoURL) impacts the entire platform, and that's possible by way of the ArgoCD Application resources. I think I can lay that out a bit more clearly in the "Configure ArgoCD" section.

I was thinking in terms of root/leaf files and how those two files work in conjunction to model a component. So with that in mind it felt like ArgoCD was introduced as a component within the platform in "Configure ArgoCD", but the root/leaf files being compared in "Render a component" were from cert-manager and not ArgoCD. That's the point where it felt like ArgoCD was "dropped," and suddenly we were talking about cert-manager without explaining why.

Let me focus on weaving those transitions into the story.