Apply suggestions from code review

Co-authored-by: Simon Gerber <simon.gerber@vshn.ch>

Author: HappyTetrahedron

docs/modules/SDDs/pages/0032-compile-pipeline.adoc

@@ -2,7 +2,7 @@
 
 :sdd_author:    Aline Abler
 :sdd_owner:     Project Syn IG
-:sdd_reviewers: Simon Gerber
+:sdd_reviewers: Simon Gerber, Tobias Brunner
 :sdd_date:      2024-06-13
 :sdd_status:    draft
 
@@ -62,8 +62,10 @@ The `accessTokenSecretName` field contains a reference to a secret.
 If it is set, the Lieutenant operator will store an access token into this secret, which can be used to access the Git repository.
 In the case of GitLab, this would be a Project Access Token with read-write access to the repository.
 
-The `ciVariables` field contains a dictionary describing variable names and corresponding values.
-These variables are added to the git repository as CI/CD variables.
+The `ciVariables` field contains a list of objects describing variable names and corresponding values.
+Each object in the list has a type that's modeled after a Kubernetes container's `env` field.
+In contrast to container environment variables, our variables only support specifying values directly (via field `value`) or by referencing a `Secret` resource (via field `valueFrom.secretKeyRef`).
+These variables are added to the Git repository as CI/CD variables.
 
 [source,yaml]
 ----
@@ -130,7 +132,7 @@ spec:
 
 Configuring the CI pipeline usually happens through files committed to the corresponding repository.
 For a Lieutenant-managed pipeline configuration, these files should be managed by Lieutenant.
-To achieve this, we can leverage the existing mechanism to commit template files to git repositories:
+To achieve this, we can leverage the existing mechanism to commit template files to Git repositories:
 
 [source,yaml]
 ----
@@ -152,7 +154,7 @@ spec:
 
 === Operator
 
-The Lieutenant Operator will be extended to automatically manage the compile pipeline for repositories where this is enabled (by way of configuring the `compilePipeline` field on the tenant and the `enableCompilePipeline` field on the cluster).
+The Lieutenant Operator will be extended to automatically manage the compile pipeline for repositories where this is enabled (by way of deploying the CI config file in the tenant and the `enableCompilePipeline` field on the cluster).
 
 Since the compile pipeline has to interact with both the tenant repository as well as the cluster catalog repositories, it must be enabled on both corresponding resources for the configuration to be functional.
 This way, it is possible to enable auto-compilation for some, but not all clusters on a tenant.
@@ -162,7 +164,7 @@ The operator will reconcile *GitRepos* as follows:
 * When `spec.accessTokenSecretName` is set, the operator generates an access token for the corresponding repository (via the repository host's API, using the API secret in `.spec.apiSecretRef`), and writes this token into a secret with the given name.
   In the case of GitLab, this is a Project Access Token.
   The operator also runs a scheduled job which refreshes these tokens when they are close to expiring, or when they no longer exist on the repository host.
-* The content of `.spec.ciVariables` is written to the repository's configuration on the git host.
+* The content of `.spec.ciVariables` is written to the repository's configuration on the Git host.
   In the case of GitLab, it is written as CI/CD variables.
 
 NOTE: If the GitRepo is of type `unmanaged`, none of these steps will be executed.