review feedback fabian

Author: maltesander

docs/modules/demos/pages/argo-cd-git-ops.adoc

@@ -26,7 +26,7 @@ You will learn how to:
 * Update Airflow DAGs or modify deployments simply by committing to Git.
 
 This hands-on approach illustrates how GitOps can simplify application lifecycle management and enforce a clear,
-auditable workflow across environments (development, staging, production).
+auditable workflow across single or multiple Kubernetes environments (development, staging, production).
 
 All products and manifests are synced and deployed via ArgoCD (except ArgoCD itself, which is bootstrapped via `stackablectl`).
 
@@ -55,17 +55,31 @@ image::argo-cd-git-ops/architecture-overview.drawio.svg[]
 
 ## Installation
 
-Install this demo on an existing Kubernetes cluster:
+WARNING: This demo should not be run alongside other demos.
+
+This demo can be installed on an existing Kubernetes cluster in two ways:
+
+### 1. Exploration - interact with the ArgoCD, Airflow and Minio web UI
 
-NOTE: In order to interact with the Git repository, this repository must be forked and additional parameters must be provided to `stackablectl`.
-This is explained in more detail in the section <<interact-with-git-repository,How to interact with the Git repository>>.
+The "easy" way. Checkout the ArgoCD, Airflow and Minio web UI, start DAGs and explore logs.
 
 [source,console]
 ----
 $ stackablectl demo install argo-cd-git-ops --namespace argo-cd
 ----
 
-WARNING: This demo should not be run alongside other demos.
+### 2. GitOps - interact with a Git repository to apply changes made in code into the cluster
+
+In addition to the exploration part, users can interact with a forked repository and apply changes to the Git repository.
+These changes then are automatically synced into the cluster.
+
+In order to interact with the Git repository, the {stackable-demo-repository}[stackable demo repository] must be forked and additional parameters must be provided to `stackablectl`.
+This is explained in more detail in the section <<interact-with-git-repository,How to interact with the Git repository>> at the bottom.
+
+[source,console]
+----
+stackablectl demo install argo-cd-git-ops --namespace argo-cd --parameters customGitUrl=<my-demo-fork-url> --parameters customGitBranch=<my-custom-branch-with-changes>
+----
 
 NOTE: ArgoCD will be deployed in the `argo-cd` namespace by `stackablectl`.
 ArgoCD itself will create other namespaces for the deployed products.
@@ -126,7 +140,8 @@ using different versions and Git sources (repository & branch) as well as the po
 
 NOTE: This demo does not use a multi cluster environment for the sake of simplicity.
 
-The following part dives deeper into the definition of the Stackable operator `ApplicationSet` and can be skipped.
+The following part dives deeper into the definition of the Stackable operator `ApplicationSet` consumed by ArgoCD.
+Users not interested in the technical parts of the `ApplicationSet` might skip this section.
 
 .Stackable operators `ApplicationSet` details
 [%collapsible]
@@ -191,7 +206,7 @@ spec:
 <1> List of Stackable operators to install.
 <2> List of clusters and Stackable release versions for each cluster.
 
-The `matrix.generators.list[].elements[]` will create a union of parameters that may be used in the `ApplicationSet` template as follows:
+The `matrix.generators.list[].elements[]` will create a union of parameters (e.g. `operator`, `cluster`, `server` and `targetRevision`), that may be used in the `ApplicationSet` template as follows:
 
 [source,yaml]
 ----
@@ -323,13 +338,15 @@ Next steps:
 [#interact-with-git-repository]
 == How to interact with ArgoCD, Airflow and the Git repository
 
-Since this Demo is hosted in the {stackable-demo-repository}[Stackable Demo repository], where merging etc. requires approval, the recommendation is to fork the {stackable-demo-repository}[Stackable Demo repository].
+Since this Demo is hosted in the {stackable-demo-repository}[Stackable Demo repository], where merging etc. requires approval,
+the recommendation is to fork and clone the {stackable-demo-repository}[Stackable Demo repository].
+This requires a two-step process:
 
-=== Forking the demo repository
+=== 1. Forking the demo repository
 
 This {github-fork}[GitHub tutorial] shows how to fork a repository.
 
-=== Cloning the demo repository
+=== 2. Cloning the demo repository
 
 Clone the demo repository:
 
@@ -339,26 +356,27 @@ git clone https://github.com/<your-username>/demos.git
 cd demos
 ----
 
-After forking the demo repository, a local copy can be cloned and the `stackablectl` install command must be parameterized with the fork URL and branch.
+After forking and cloning a local copy, the `stackablectl` install command must be parameterized with the forked repository URL and branch.
 
 [source,console]
 ----
 stackablectl demo install argo-cd-git-ops --namespace argo-cd --parameters customGitUrl=<my-demo-fork-url> --parameters customGitBranch=<my-custom-branch-with-changes>
 ----
 
-=== Making changes to the repository
+== Making changes to the repository
 
-Edit manifests or add new DAG files within your cloned repository:
+After obaining a local copy, changes made to Stackable manifests or Airflow DAGs can be integrated via GitOps.
+Edit Stackable manifests or add new DAGs within your cloned repository:
 
 * Manifests are in: `demos/argo-cd-git-ops/manifests/`
 * Airflow DAGs are in: `demos/argo-cd-git-ops/dags/`
 
-==== Increase Airflow webserver replicas
+=== 1. Increase Airflow webserver replicas
 
 Assuming your working directory is the root of the forked demo repository, try to increase the `spec.webservers.roleGroups.<role-group>.replicas` in the folder `demos/argo-cd-git-ops/manifests/airflow/airflow.yaml`.
 Once this is pushed / merged, ArgoCD should sync the changes and you should see more webserver pods.
 
-==== Add new Airflow DAGs
+=== 2. Add new Airflow DAGs
 
 In the `demos/argo-cd-git-ops/manifests/airflow/airflow.yaml` manifest you have to adapt the git-sync configuration for DAGs to the forked repository:
 
@@ -398,7 +416,7 @@ File Path                                                               PID  Run
 
 If another DAG is displayed, try to refresh the Airflow UI if changes have not been propagated yet.
 
-==== Commit and push changes
+=== 3. Commit and push changes
 
 [source,console]
 ----