docs: Style and formatting improvements to User Guide (#22622)

Signed-off-by: Oliver Gondža <ogondza@gmail.com>
Co-authored-by: rumstead <37445536+rumstead@users.noreply.github.com>

docs/user-guide/application_sources.md

@@ -6,7 +6,7 @@ Argo CD supports several different ways in which Kubernetes manifests can be def
 
 * [Kustomize](kustomize.md) applications
 * [Helm](helm.md) charts
-* A directory of YAML/JSON/Jsonnet manifests, including [Jsonnet](jsonnet.md).
+* A directory of YAML, JSON, or [Jsonnet](jsonnet.md) manifests.
 * Any [custom config management tool](../operator-manual/config-management-plugins.md) configured as a config management plugin
 
 ## Development

docs/user-guide/auto_sync.md

@@ -18,7 +18,7 @@ spec:
   syncPolicy:
     automated: {}
 ```
-Application CRD now also support explicitly setting automated sync to be turn on or off by using `spec.syncPolicy.automated.enabled` flag to true or false. When `enable` field is set to true, Automated Sync is active and when set to false controller will skip automated sync even if `prune`, `self-heal` and `allowEmpty` are set.
+Application CRD now also support explicitly setting automated sync to be turned on or off by using `spec.syncPolicy.automated.enabled` flag to true or false. When `enable` field is set to true, Automated Sync is active and when set to false controller will skip automated sync even if `prune`, `self-heal` and `allowEmpty` are set.
 ```yaml
 spec:
   syncPolicy:
@@ -27,7 +27,7 @@ spec:
 ```
 
 !!!note 
-  Setting `spec.syncPolicy.automated.enabled` flag to null will be treated as automated sync as enabled. When using `enabled` field set to false, fields like `prune`, `self-heal` and `allowEmpty` can be set without enabling them.
+    Setting the `spec.syncPolicy.automated.enabled` flag to null will be treated as if automated sync is enabled. When the `enabled` field is set to false, fields like `prune`, `selfHeal` and `allowEmpty` can be set without enabling them.
 
 ## Temporarily toggling auto-sync for applications managed by ApplicationSets
 
@@ -82,7 +82,7 @@ when the live cluster's state deviates from the state defined in Git, run:
 argocd app set <APPNAME> --self-heal
 ```
 
-Or by setting the self heal option to true in the automated sync policy:
+Or by setting the self-heal option to true in the automated sync policy:
 
 ```yaml
 spec:
@@ -100,7 +100,7 @@ Disabling self-heal does not guarantee that live cluster changes won't be revert
 * Automated sync will only attempt one synchronization per unique combination of commit SHA1 and
   application parameters. If the most recent successful sync in the history was already performed
   against the same commit-SHA and parameters, a second sync will not be attempted, unless `selfHeal` flag is set to true.
-* If `selfHeal` flag is set to true then sync will be attempted again after self heal timeout (5 seconds by default)
+* If the `selfHeal` flag is set to true, then the sync will be attempted again after self-heal timeout (5 seconds by default)
 which is controlled by `--self-heal-timeout-seconds` flag of `argocd-application-controller` deployment.
 * Automatic sync will not reattempt a sync if the previous sync attempt against the same commit-SHA
   and parameters had failed.

docs/user-guide/diff-strategies.md

@@ -17,16 +17,14 @@ Argo CD currently has 3 different strategies to calculate diffs:
 
 ## Structured-Merge Diff
 
-!!! warning "Beta Feature (Since v2.5.0)"
-    This feature is in the [Beta][1] stage. It is generally considered stable, but there may be unhandled edge cases.
+!!! warning "Feature Discontinued"
+    After different issues were identified by the community, this strategy is being discontinued in favour of Server-Side Diff.
 
 This diff strategy is automatically used when Server-Side Apply
 sync option is enabled. It uses the [structured-merge-diff][2] library
 used by Kubernetes to calculate diffs based on fields ownership. There
 are some challenges using this strategy to calculate diffs for CRDs
-that define default values. After different issues were identified by
-the community, this strategy is being discontinued in favour of
-Server-Side Diff.
+that define default values.
 
 ## Server-Side Diff
 
@@ -65,7 +63,7 @@ Application.
 
 Add the following entry in the argocd-cmd-params-cm configmap:
 
-```
+```yaml
 apiVersion: v1
 kind: ConfigMap
 metadata:
@@ -82,7 +80,7 @@ after applying this configuration.
 
 Add the following annotation in the Argo CD Application resource:
 
-```
+```yaml
 apiVersion: argoproj.io/v1alpha1
 kind: Application
 metadata:
@@ -97,7 +95,7 @@ If Server-Side Diff is enabled globally in your Argo CD instance, it
 is possible to disable it at the application level. In order to do so,
 add the following annotation in the Application resource:
 
-```
+```yaml
 apiVersion: argoproj.io/v1alpha1
 kind: Application
 metadata:
@@ -115,7 +113,7 @@ Server-Side Diff does not include changes made by mutation webhooks by
 default. If you want to include mutation webhooks in Argo CD diffs add
 the following annotation in the Argo CD Application resource:
 
-```
+```yaml
 apiVersion: argoproj.io/v1alpha1
 kind: Application
 metadata:
@@ -128,7 +126,7 @@ Note: This annotation is only effective when Server-Side Diff is
 enabled. To enable both options for a given application add the
 following annotation in the Argo CD Application resource:
 
-```
+```yaml
 apiVersion: argoproj.io/v1alpha1
 kind: Application
 metadata:

docs/user-guide/diffing.md

@@ -6,7 +6,7 @@ It is possible for an application to be `OutOfSync` even immediately after a suc
   resulting in an `OutOfSync` status indicating a missing field was detected.
 - The sync was performed (with pruning disabled), and there are resources which need to be deleted.
 - A controller or [mutating webhook](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook) is altering the object after it was
-  submitted to Kubernetes in a manner which contradicts Git.
+  submitted to Kubernetes so it differs from the one in Git.
 - A Helm chart is using a template function such as [`randAlphaNum`](https://github.com/helm/charts/blob/master/stable/redis/templates/secret.yaml#L16),
   which generates different data every time `helm template` is invoked.
 - For Horizontal Pod Autoscaling (HPA) objects, the HPA controller is known to reorder `spec.metrics`
@@ -94,7 +94,7 @@ data:
     - '.webhooks[]?.clientConfig.caBundle'
 ```
 
-Resource customization can also be configured to ignore all differences made by a managedField.manager at the system level. The example below shows how to configure Argo CD to ignore changes made by `kube-controller-manager` in `Deployment` resources.
+Resource customization can also be configured to ignore all differences made by a `managedField.manager` at the system level. The example below shows how to configure Argo CD to ignore changes made by `kube-controller-manager` in `Deployment` resources.
 
 ```yaml
 data:
@@ -103,7 +103,7 @@ data:
     - kube-controller-manager
 ```
 
-It is possible to configure ignoreDifferences to be applied to all resources in every Application managed by an Argo CD instance. In order to do so, resource customizations can be configured like in the example below:
+It is possible to configure `ignoreDifferences` to be applied to all resources in every Application managed by an Argo CD instance. In order to do so, resource customizations can be configured like in the example below:
 
 ```yaml
 data:
@@ -129,7 +129,8 @@ data:
 
 If you rely on the status field being part of your desired state, although this is not recommended, the `ignoreResourceStatusField` setting can be used to configure this behavior.
 
-**Note**: Since it is common for `CustomResourceDefinitions` to have their `status` commited to Git, consider using `crd` over `none`.
+!!! note
+    Since it is common for `CustomResourceDefinitions` to have their `status` commited to Git, consider using `crd` over `none`.
 
 ### Ignoring RBAC changes made by AggregateRoles
 

docs/user-guide/gpg-verification.md

@@ -211,7 +211,7 @@ argocd proj remove-signature-key myproj 4AEE18F83AFDEB23
 #### Showing allowed key IDs for a project
 
 To see which key IDs are allowed for a given project, you can inspect the
-output of the `argocd proj get` command, i.e for a project named `gpg`:
+output of the `argocd proj get` command, i.e. for a project named `gpg`:
 
 ```bash
 $ argocd proj get gpg

docs/user-guide/helm.md

@@ -390,9 +390,9 @@ RUN helm plugin install ${GCS_PLUGIN_REPO} --version ${GCS_PLUGIN_VERSION}
 ENV HELM_PLUGINS="/home/argocd/.local/share/helm/plugins/"
 ```
 
-You have to remember about `HELM_PLUGINS` environment property - this is required for plugins to work correctly.
+The `HELM_PLUGINS` environment property required for ArgoCD to locale plugins correctly.
 
-After that you have to use your custom image for ArgoCD installation.
+Once built, use the custom image for ArgoCD installation.
 
 ### Using `initContainers`
 Another option is to install Helm plugins via Kubernetes `initContainers`.
@@ -519,7 +519,6 @@ spec:
 ```
 
 
-
 ## Helm `--skip-tests`
 
 By default, Helm includes test manifests when rendering templates. Argo CD currently skips manifests that include hooks not supported by Argo CD, including [Helm test hooks](https://helm.sh/docs/topics/chart_tests/). While this feature covers many testing use cases, it is not totally congruent with --skip-tests, so the --skip-tests option can be used.
@@ -537,4 +536,4 @@ spec:
   source:
     helm:
       skipTests: true # or false
-```
+```

docs/user-guide/multiple_sources.md

@@ -80,8 +80,7 @@ If the `path` field is set in the `$values` source, Argo CD will attempt to gene
 at that URL. If the `path` field is not set, Argo CD will use the repository solely as a source of value files.
 
 !!! note
-    Sources with the `ref` field set must not also specify the `chart` field. Argo CD does not currently support using  
-    another Helm chart as a source for value files.
+    Sources with the `ref` field set cannot include the `chart` field. Currently, Argo CD does not support using another Helm chart as a source for value files.
 
 !!! note
     Even when the `ref` field is configured with the `path` field, `$value` still represents the root of sources with the `ref` field. Consequently, `valueFiles` must be specified as relative paths from the root of sources.

docs/user-guide/parameters.md

@@ -26,8 +26,8 @@ argocd app set guestbook -p ingress.enabled=true
 argocd app set guestbook -p ingress.hosts[0]=guestbook.myclusterurl
 ```
 
-The `argocd app set` [command](./commands/argocd_app_set.md) supports more tool-specific flags such as `--kustomize-image`, `--jsonnet-ext-var-str` etc
-flags. You can also specify overrides directly in the source field on application spec. Read more about supported options in corresponded tool [documentation](./application_sources.md).
+The `argocd app set` [command](./commands/argocd_app_set.md) supports more tool-specific flags such as `--kustomize-image`, `--jsonnet-ext-var-str`, etc.
+You can also specify overrides directly in the source field on the application spec. Read more about supported options in the corresponding tool [documentation](./application_sources.md).
 
 ## When To Use Overrides?
 
@@ -81,7 +81,7 @@ are sourcing multiple applications from a single path in your repository.
 The application specific file must be named `.argocd-source-<appname>.yaml`,
 where `<appname>` is the name of the application the overrides are valid for.
 
-If there exists an non-application specific `.argocd-source.yaml`, parameters
+If there exists a non-application specific `.argocd-source.yaml`, parameters
 included in that file will be merged first, and then the application specific
 parameters are merged, which can also contain overrides to the parameters
 stored in the non-application specific file.

docs/user-guide/private-repositories.md

@@ -63,7 +63,7 @@ Of course, you can also use this in combination with the `--username` and `--pas
 Your TLS client certificate and corresponding key can also be configured using the UI, see instructions for adding Git repos using HTTPS.
 
 !!! note
-    Your client certificate and key data must be in PEM format, other formats (such as PKCS12) are not understood. Also make sure that your certificate's key is not password protected, otherwise it cannot be used by Argo CD.
+    Your client certificate and key data must be in PEM format, other formats (such as PKCS12) are not supported. Also make sure that your certificate's key is not password protected, otherwise it cannot be used by Argo CD.
 
 !!! note
     When pasting TLS client certificate and key in the text areas in the web UI, make sure they contain no unintended line breaks or additional characters.

docs/user-guide/projects.md

@@ -195,7 +195,7 @@ argocd proj role create-token PROJECT ROLE-NAME
 argocd proj role delete-token PROJECT ROLE-NAME ISSUED-AT
 ```
 
-Since the JWT tokens aren't stored in Argo CD, they can only be retrieved when they are created. A user can leverage them in the cli by either passing them in using the `--auth-token` flag or setting the ARGOCD_AUTH_TOKEN environment variable. The JWT tokens can be used until they expire or are revoked.  The JWT tokens can created with or without an expiration, but the default on the cli is creates them without an expirations date.  Even if a token has not expired, it cannot be used if the token has been revoked.
+Since the JWT tokens aren't stored in Argo CD, they can only be retrieved when they are created. A user can leverage them in the cli by either passing them in using the `--auth-token` flag or setting the ARGOCD_AUTH_TOKEN environment variable. The JWT tokens can be used until they expire or are revoked.  The JWT tokens can be created with or without an expiration.  By default, the cli creates them without an expirations date.  Even if a token has not expired, it cannot be used if the token has been revoked.
 
 Below is an example of leveraging a JWT token to access a guestbook application.  It makes the assumption that the user already has a project named myproject and an application called guestbook-default.
 
@@ -297,7 +297,7 @@ It is possible to offer a self-service process for developers so that they can a
 For this purpose Argo CD supports project-scoped repositories and clusters.
 
 To begin the process, Argo CD admins must configure RBAC security to allow this self-service behavior.
-For example, to allow users to add project scoped repositories and admin would have to add the following RBAC rules:
+For example, to allow users to add project scoped repositories an admin would have to add the following RBAC rules:
 
 ```
 p, proj:my-project:admin, repositories, create, my-project/*, allow
@@ -335,12 +335,12 @@ stringData:
 ```
 
 !!! warning
-Please keep in mind when using a project-scoped repository, only applications or applicationsets with a matching project 
-name can make use of it. When using an applicationset with a Git generator that also makes use of a templated `project` 
-(i.e. it contains ``{{ ... }}``) only non-scoped repositories can be used with the applicationset (i.e. repositories 
-that do _not_ have a `project` set).
+    Please keep in mind when using a project-scoped repository, only applications or applicationsets with a matching project 
+    name can make use of it. When using an applicationset with a Git generator that also makes use of a templated `project` 
+    (i.e. it contains ``{{ ... }}``) only non-scoped repositories can be used with the applicationset (i.e. repositories 
+    that do _not_ have a `project` set).
 
-All the examples above talk about Git repositories, but the same principles apply to clusters as well.
+All the examples above concern Git repositories, but the same principles apply to clusters as well.
 
 ```yaml
 apiVersion: v1

docs/user-guide/selective_sync.md

@@ -4,10 +4,10 @@ A *selective sync* is one where only some resources are sync'd. You can choose w
 
 ![selective sync](../assets/selective-sync.png)
 
-When doing so, bear in mind:
+When doing so, bear in mind that:
 
 * Your sync is not recorded in the history, and so rollback is not possible.
-* Hooks are not run.
+* [Hooks](resource_hooks.md) are not run.
 
 ## Selective Sync Option
 

docs/user-guide/sync-options.md

@@ -1,6 +1,6 @@
 # Sync Options
 
-Argo CD allows users to customize some aspects of how it syncs the desired state in the target cluster. Some Sync Options can be defined as annotations in a specific resource. Most of the Sync Options are configured in the Application resource `spec.syncPolicy.syncOptions` attribute. Multiple Sync Options which are configured with the `argocd.argoproj.io/sync-options` annotation can be concatenated with a `,` in the annotation value; white spaces will be trimmed.
+Argo CD allows users to customize some aspects of how it syncs the desired state in the target cluster. Some Sync Options can be defined as annotations in a specific resource. Most of the Sync Options are configured in the Application resource `spec.syncPolicy.syncOptions` attribute. Multiple Sync Options which are configured with the `argocd.argoproj.io/sync-options` annotation can be concatenated with a `,` in the annotation value; white-space will be trimmed.
 
 Below you can find details about each available Sync Option:
 
@@ -43,7 +43,7 @@ annotation to the application.
 
 ## Disable Kubectl Validation
 
-For a certain class of objects, it is necessary to `kubectl apply` them using the `--validate=false` flag. Examples of this are Kubernetes types which uses `RawExtension`, such as [ServiceCatalog](https://github.com/kubernetes-incubator/service-catalog/blob/master/pkg/apis/servicecatalog/v1beta1/types.go#L497). You can do using this annotations:
+For a certain class of objects, it is necessary to `kubectl apply` them using the `--validate=false` flag. Examples of this are Kubernetes types which uses `RawExtension`, such as [ServiceCatalog](https://github.com/kubernetes-incubator/service-catalog/blob/master/pkg/apis/servicecatalog/v1beta1/types.go#L497). You can do using this annotation:
 
 
 ```yaml
@@ -58,8 +58,8 @@ If you want to exclude a whole class of objects globally, consider setting `reso
 
 When syncing a custom resource which is not yet known to the cluster, there are generally two options:
 
-1) The CRD manifest is part of the same sync. Then Argo CD will automatically skip the dry run, the CRD will be applied and the resource can be created.
-2) In some cases the CRD is not part of the sync, but it could be created in another way, e.g. by a controller in the cluster. An example is [gatekeeper](https://github.com/open-policy-agent/gatekeeper),
+1. The CRD manifest is part of the same sync. Then Argo CD will automatically skip the dry run, the CRD will be applied and the resource can be created.
+2. In some cases the CRD is not part of the sync, but it could be created in another way, e.g. by a controller in the cluster. An example is [gatekeeper](https://github.com/open-policy-agent/gatekeeper),
 which creates CRDs in response to user defined `ConstraintTemplates`. Argo CD cannot find the CRD in the sync and will fail with the error `the server could not find the requested resource`.
 
 To skip the dry run for missing resource types, use the following annotation:
@@ -100,7 +100,7 @@ annotation to the application.
 
 ## Selective Sync
 
-Currently when syncing using auto sync Argo CD applies every object in the application.
+Currently, when syncing using auto sync Argo CD applies every object in the application.
 For applications containing thousands of objects this takes quite a long time and puts undue pressure on the api server.
 Turning on selective sync option which will sync only out-of-sync resources.
 

docs/user-guide/sync_windows.md

@@ -32,11 +32,14 @@ These windows affect the running of both manual and automated syncs but allow an
 for manual syncs which is useful if you are only interested in preventing automated syncs or if you need to temporarily 
 override a window to perform a sync.
 
-The windows work in the following way. If there are no windows matching an application then all syncs are allowed. If there
-are any `allow` windows matching an application then syncs will only be allowed when there is an active `allow` window. If there
-are any `deny` windows matching an application then all syncs will be denied when the `deny` windows are active. If there is an
-active matching `allow` and an active matching `deny` then syncs will be denied as `deny` windows override `allow` windows. The
-UI and the CLI will both display the state of the sync windows. The UI has a panel which will display different colours depending
+The windows work in the following way:
+
+- If there are no windows matching an application then all syncs are allowed.
+- If there are any `allow` windows matching an application then syncs will only be allowed when there is an active `allow` window.
+- If there are any `deny` windows matching an application then all syncs will be denied when the `deny` windows are active.
+- If there is an active matching `allow` and an active matching `deny` then syncs will be denied as `deny` windows override `allow` windows.
+
+The UI and the CLI will both display the state of the sync windows. The UI has a panel which will display different colours depending
 on the state. The colours are as follows. `Red: sync denied`, `Orange: manual allowed` and `Green: sync allowed`.
 
 To display the sync state using the CLI:

docs/user-guide/tool_detection.md

@@ -5,7 +5,7 @@ The tool used to build an application is detected as follows:
 If a specific tool is explicitly configured, then that tool is selected to create your application's manifests.
 
 The tool can be explicitly specified in the Application custom resource like this:
-```
+```yaml
 apiVersion: argoproj.io/v1alpha1
 kind: Application
 metadata: