chore(backport release-1.2): docs: improve Argo CD integration docume…

…nt (#3344)

Co-authored-by: Hidde Beydals <[email protected]>

docs/docs/60-new-docs/50-user-guide/20-how-to-guides/25-argo-cd-integration.md

@@ -13,10 +13,6 @@ such processes. Because such orchestration naturally entails some direct
 and indirect integration with Argo CD, this page details certain key
 elements of the interactions between the two systems.
 
-:::note
-This page is a work in progress. Thank you for your patience as we work to add more details.
-:::
-
 ## Updating Argo CD Applications
 
 In the course of orchestrating the transition of an application instance
@@ -28,6 +24,22 @@ Often, these updates entail little more than modifying an `Application`'s
 `operation` field to force the `Application` to be synced to recently
 updated desired state.
 
+```yaml
+steps:
+- uses: argocd-update
+  config:
+    apps:
+    - name: my-app
+      sources:
+      - repoURL: https://github.com/example/repo.git
+        desiredRevision: <commit-hash>
+```
+
+:::info
+For in-depth information on the usage of the `argocd-update` step, see the
+[examples](../60-reference-docs/30-promotion-steps/argocd-update.md#examples).
+:::
+
 ### Authorizing Updates
 
 Performing updates of any kind to an `Application` resource naturally
@@ -64,3 +76,21 @@ metadata:
 spec:
   # Application Specifications
 ```
+
+## Health Checks
+
+When a `Promotion` uses an `argocd-update` step to update an `Application`, a
+[health check](../60-reference-docs/30-promotion-steps/argocd-update.md#health-checks)
+is registered for the `Stage` that the `Promotion` is targeting. This health
+check is used to continuously monitor the
+[health of the `Application`](https://argo-cd.readthedocs.io/en/stable/operator-manual/health/)
+that was updated by the `argocd-update` step as part of the `Stage` health.
+
+:::info
+It is important to note that `Stage` health is not determined solely by the
+health of the `Application`(s) that the `Stage` is managing. The health of the
+`Stage` is determined by the health of all `Application` resources that the
+`Stage` is managing, _as well as_ any other indicators of health that are
+part of the `Stage`'s definition. For example, a `Stage` may be considered
+unhealthy if the latest `Promotion` to that `Stage` failed.
+:::

docs/docs/60-new-docs/50-user-guide/60-reference-docs/30-promotion-steps/argocd-update.md

@@ -88,16 +88,21 @@ window. (The step's default timeout is five minutes.)_
 
 The `argocd-update` step is unique among all other built-in promotion steps in
 that, on successful completion, it will register health checks to be performed
-upon the target Stage on an ongoing basis. This health check configuration is
+upon the target `Stage` on an ongoing basis. This health check configuration is
 _opaque_ to the rest of Kargo and is understood only by health check
 functionality built into the step. This permits Kargo to factor the health and
-sync state of Argo CD `Application` resources into the overall health of a Stage
-without requiring Kargo to understand `Application` health directly.
+sync state of Argo CD `Application` resources into the overall health of a
+`Stage` without requiring Kargo to understand `Application` health directly.
 
 :::info
 Although the `argocd-update` step is the only promotion step to currently
 utilize this health check framework, we anticipate that future built-in and
 third-party promotion steps will take advantage of it as well.
+
+Because of this, the health of a `Stage` is not necessarily a simple
+reflection of the `Application` resource it manages. It can also be influenced
+by other `Application` resources that are updated by other promotion steps,
+or by a `Promotion` which failed to complete successfully.
 :::
 
 ## Examples