docs: update kargo quickstart guide

[fykaa]

https://docs.kargo.io/quickstart

[netlify]

✅ Deploy Preview for docs-kargo-akuity-io ready!

Name	Link
🔨 Latest commit	d1519bd
🔍 Latest deploy log	https://app.netlify.com/sites/docs-kargo-akuity-io/deploys/66f67ff0ae0ed200088a1d00
😎 Deploy Preview	https://deploy-preview-2521.kargo.akuity.io
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 48.82%. Comparing base (5af701f) to head (fd27eb6).
Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2521   +/-   ##
=======================================
  Coverage   48.82%   48.82%           
=======================================
  Files         270      270           
  Lines       23941    23941           
=======================================
  Hits        11690    11690           
  Misses      11620    11620           
  Partials      631      631           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[krancour]

General comment -- this is a modest improvement. 👍

Let's also plan, however, on providing more UI-centric instructions. i.e. Instead of just "this is what it will look like when you click this link," we also need "click this, then click that," as an alternative to the CLI-based instructions.

[fykaa]

Addressed all the reviews @kencochrane

Regarding the need for more clarity on clicks, I believe that adding multiple screenshots inline may not be the most user-friendly approach.
Should I consider using Supademo to illustrate each component instead?

[krancour]

Regarding the need for more clarity on clicks, I believe that adding multiple screenshots inline may not be the most user-friendly approach.

I agree. So let's not constrain the effort of providing the quickstart with a UI perspective to just adding screenshots. There are other effective ways to document navigation of a UI.

This page has an example of how (stylystically speaking) we have documented certain steps on GitHub:

https://kargo.akuity.io/how-to-guides/managing-credentials/#github-app-authentication

There is also information about how to do this in the "Referencing UI elements" section of the style guide:

https://github.com/akuity/kargo/blob/main/docs/STYLE_GUIDE.md#referencing-ui-elements

Should I consider using Supademo to illustrate each component instead?

I want to see how far we can get without falling back on this. I'm entirely unopposed to it as a supplement to proper docs, but I don't want to skimp on the text-based docs specifically because they're ingestible by search engines and LLMs.

[fykaa]

@krancour I’ve added some styles to guide users with actionable steps, similar to the approach used in other guides. Do you think there’s room for further improvement in the Quickstart guide at this stage?

As a new reader, my main concern was the lack of graphics, which I believe is now addressed here. Everything else on the page seems to work well. Do you think we need to enhance navigation further, or is it good as is?

[krancour]

Additional notes that I couldn't add inline because they weren't near any changes...

If we're making this more UI-centric, I think we need some brief explanatory text around line 289 (just before logging in using the Kargo CLI) about why we're using the CLI: There's a lot of configuration and it's easiest to create it declaratively.

I also think that section might be a good place to add some tabs showing how that step can be accomplished with either the Kargo CLI or kubectl. (kubectl is actually easier because there's no logging in required.) If you do this, you could also edit the section on installing the CLI so that it's designated as an optional step.

[krancour]

I also think that section might be a good place to add some tabs showing how that step can be accomplished with either the Kargo CLI or kubectl. (kubectl is actually easier because there's no logging in required.) If you do this, you could also edit the section on installing the CLI so that it's designated as an optional step.

I put more thought into this...

I think we should indeed use tabs to give the user the choice of kubectl or the kargo CLI for declaratively setting up the Project and:

• Use a line of introductory text above indicating there are two ways to proceed with the steps in this section.

• Make kubectl the default tab as there's less effort involved -- no download required; no login required.

• Move the whole section on downloading/installing the CLI into the kargo tab.

This will make the quickstart considerably shorter in appearance and in terms of steps a user must complete unless they opt-in to using kargo instead of kubectl.

I don't (yet?) want to remove kargo CLI bits entirely because I think just having the option there calls new users' attention to the fact it exists -- something that may be easily overlooked otherwise.

[akuitybot]

Successfully created backport PR for release-1.0:

• chore(backport release-1.0): docs: update kargo quickstart guide #2840