Adjust the docs to the new documentation guidelines (kyma-project#10224)

* Adjust the docs to the new documentation guidelines

* Language and formatting fixes

* Apply review suggestions

* Further review suggestions applied

.githooks/README.md

@@ -1,4 +1,4 @@
-# Git hooks
+# Git Hooks
 
 ## Overview
 
@@ -11,24 +11,24 @@ To do so, run this command in the root of your `test-infra` Git repository:
 ```shell
 git config core.hooksPath .githooks
 ```
-Now your local Git repository uses Git hooks from the `.githooks` path.
+Now, your local Git repository uses Git hooks from the `.githooks` path.
 
 ## Troubleshooting
 
-### Mac: VCS integration in GoLand can't use applications installed by Homebrew
+### Mac: VCS Integration in GoLand Can't Use Applications Installed by Homebrew
 
 This is an issue that is known for all JetBrains IDEs which run on a Mac.
-Upon startup, GoLand will initialize the `PATH` based on the macOS' `launchd` path.
+Upon startup, GoLand initializes the `PATH` based on the macOS' `launchd` path.
 <!-- markdown-link-check-disable-next-line -->
 The [solution](https://apple.stackexchange.com/questions/51677/how-to-set-path-for-finder-launched-applications) is to add `/usr/local/bin` path to the system `PATH` variable by using the command listed below.
 ```shell
 sudo launchctl config user path /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
 ```
->**CAUTION:** This change will be applied to ALL uses of a computer!
+>**CAUTION:** This change is applied to ALL uses of a computer!
 
 After running this command, reboot your machine to apply changes.
 
-## Hooks list
+## Hooks List
 |Name|Type|Description|
 |---|---|---|
-|01-rendertemplates.sh|pre-commit|Automatically renders templates and adds the resulted files to the commit if there were any changes.| 
+|01-rendertemplates.sh|pre-commit|Automatically renders templates and adds the resulting files to the commit if there were any changes.| 

cmd/cloud-run/rotate-service-account/README.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-RotateServiceAccount creates a new key for a GCP service account and updates the required secret data. It's triggered by a  Pub/Sub message sent by a secret stored in Secret Manager. It runs as a cloud run container.
+RotateServiceAccount creates a new key for a Google Cloud service account and updates the required secret data. It's triggered by a  Pub/Sub message sent by a secret stored in Secret Manager. It runs as a cloud run container.
 
 1. Secret Manager sends a Pub/Sub message to `secret-manager-notifications` Pub/Sub topic.
 3. RotateServiceAccount checks if the value of the **eventType** attribute is set to `SECRET_ROTATE`; if not, it stops its execution.

cmd/cloud-run/service-account-keys-cleaner/README.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The Cloud Run service deletes old keys for a GCP service account and updates the required secret data for all service account secrets stored in the Secret Manager. The service is triggered by a Cloud Scheduler job.
+The Cloud Run service deletes old keys for a Google Cloud service account and updates the required secret data for all service account secrets stored in the Secret Manager. The service is triggered by a Cloud Scheduler job.
 
 1. Cloud Scheduler calls the service-account-keys-cleaner service.
 2. For each secret stored in Secret Manager, the service executes the following steps:
@@ -29,6 +29,6 @@ The Cloud Function accepts the following GET parameters:
 
 | Name                           | Required | Description                                                           |
 | :----------------------------- | :------: | :-------------------------------------------------------------------- |
-| **project**                    |    Yes   | The name of the GCP project with Secret Manager.|
+| **project**                    |    Yes   | The name of the Google Cloud project with Secret Manager.|
 | **age**                        |    No    | The age in hours that the latest version of a secret has to exist before old versions can be deleted. It defaults to `5`. |
 | **dry_run**                    |    No    | The value controlling the `dry run` mode. It defaults to `false`.|

cmd/external-plugins/automated-approver/README.md

@@ -11,22 +11,22 @@ With the Automated Approver tool, you can automatically approve a pull request (
 Automated Approver is a Prow plugin written in Golang. GitHub events are dispatched by Prow to the Automated Approver plugin. Automated Approver runs in a Prow Kubernetes cluster along with Prow components.
 
 Automated Approver reacts to the following events:
- - pull request review requested
- - pull request synchronized
+ - PR review requested
+ - PR synchronized
  - review dismissed
 
-To identify PRs that must be approved by the tool, Automated Approver evaluates rules defined in the `rules.yaml` file. Rules are defined per organization, repository, or user entity. You can define the following conditions in the rules:
+To identify PRs that must be approved by the tool, Automated Approver evaluates rules defined in the `rules.yaml` file. The rules are defined per organization, repository, or user entity. You can define the following conditions in the rules:
  - PR required labels
  - PR changed files
 
-If a PR meets the conditions, the tool checks if the PR tests are finished. The `Tide` context is an exception: pending status for `Tide` is ignored. The tool uses a backoff algorithm for sleep duration between subsequent status checks. A `wait-for-statuses-timeout` flag defines a timeout period while waiting for statuses to finish and reports its state back to GitHub. Once the tests are finished, it checks whether they were successful. Currently, the tool doesn't support optional tests. When all checks and conditions are met, the tool approves the PR.
+If a PR meets the conditions, the tool checks if the PR tests are finished. The `Tide` context is an exception: the `pending` status for `Tide` is ignored. The tool uses a backoff algorithm for sleep duration between subsequent status checks. A `wait-for-statuses-timeout` flag defines a timeout period while waiting for statuses to finish and reports its state back to GitHub. Once the tests are finished, it checks whether they were successful. Currently, the tool doesn't support optional tests. When all checks and conditions are met, the tool approves the PR.
 
 Automated Approver uses the identity of a dedicated GitHub user to approve PRs. Depending on repository configuration, the user must have `write` permission on the repository, must be added to repository collaborators, and as a code owner in the `CODEOWNERS` file.
 
 ## How to Use It
 
 You configure Automated Approver with CLI flags. The flags are defined in the following files in our repository and their dependencies:
-- Automated Approver [configuration flags](https://github.com/kyma-project/test-infra/blob/5242421660dab5979a763bcd596eba48bafe093d/cmd/external-plugins/automated-approver/main.go#L39) 
+- Automated Approver [configuration flags](https://github.com/kyma-project/test-infra/blob/5242421660dab5979a763bcd596eba48bafe093d/cmd/external-plugins/automated-approver/main.go#L39). 
 - External plugin [configuration flags](https://github.com/kyma-project/test-infra/blob/5242421660dab5979a763bcd596eba48bafe093d/pkg/prow/externalplugin/externalplugin.go#L68) define the needed flags' values in the Pod specification and apply them to the Kubernetes cluster
 
 Additionally, Automated Approver uses rules to approve PRs. You define the rules as a YAML file and apply them to the Kubernetes cluster as a ConfigMap. You must mount this ConfigMap to the Pod that runs Automated Approver.

cmd/gardener-rotate/README.md

@@ -32,9 +32,9 @@ serviceAccounts:
   - k8sServiceAccount: "sa-neighbor-robot" # Kubernetes service account name to rotate
     k8sNamespace: "garden-neighbors" # Kubernetes service account namespace
     k8sDuration: 5184000 # vailidity of the new token in seconds
-    gcpSecretManagerSecretName: "trusted_default_gardener-neighbors-kubeconfig" # name of the GCP secret where the kubeconfig is stored
-    gcpProjectName: "sap-kyma-prow" # name of the GCP project with Secret Manager
-    gcpKeepOld: false # should old versions of the GCP secret be disabled, false by default
+    gcpSecretManagerSecretName: "trusted_default_gardener-neighbors-kubeconfig" # name of the Google Cloud secret where the kubeconfig is stored
+    gcpProjectName: "sap-kyma-prow" # name of the Google Cloud project with Secret Manager
+    gcpKeepOld: false # should old versions of the Google Cloud secret be disabled, false by default
 ```
 
 
@@ -44,7 +44,7 @@ See the list of flags available for the `promote` command:
 
 | Name                      | Required | Description                                                                                          |
 | :------------------------ | :------: | :--------------------------------------------------------------------------------------------------- |
-| **--service-account**     |   Yes    | Path to the GCP service account credentials file. This credential is used to access Secret Manager.|
+| **--service-account**     |   Yes    | Path to the Google Cloud service account credentials file. This credential is used to access Secret Manager.|
 | **--kubeconfig**          |   Yes    | Path to the Gardener kubeconfig file. This credential is used for token rotation.|
 | **--config-file**         |   Yes    | Path to the `gardener-rotate` configuration file.|
 | **--dry-run**             |   No     | The boolean value that controls the dry-run mode. It defaults to `true`.|

cmd/image-builder/README.md

@@ -65,9 +65,9 @@ Here is an example of a ProwJob for building images with ADO backend:
               name: kaniko-build-config
 ```
 
-It builds the `buildkit-image-builder` image using the image-builder ADO backend.
+It builds the `buildkit-image-builder` image using the `image-builder` ADO backend.
 It uses the Dockerfile from the `cmd/image-builder/images/buildkit/Dockerfile` path and the config from the `kaniko-build-config` ConfigMap.
-Because it's a presubmit ProwJob it does not sign the image.
+Because it's a presubmit ProwJob, it does not sign the image.
 Signing images is supported only in postsubmit ProwJobs.
 
 ## Configuration
@@ -101,12 +101,12 @@ Here is the list of environment variables used by Image Builder:
 
 - **REPO_NAME**: The name of the repository with source code to build an image from.
 - **REPO_OWNER**: The owner of the repository with source code.
-- **JOB_TYPE**: The type of job. This can be either `presubmit` or `postsubmit`. `presubmit` represents a pull request job, and `postsubmit`
+- **JOB_TYPE**: The type of job. This can be either `presubmit` or `postsubmit`. `presubmit` represents a pull request (PR) job, and `postsubmit`
   represents a push job.
-- **PULL_NUMBER**: The number of the pull request.
-- **PULL_BASE_SHA**: The base SHA of the pull request or push commit SHA.
-- **PULL_PULL_SHA**: The pull request head SHA of the pull request.
-- **ADO_PAT**: The Azure DevOps Personal Access Token. It's used in the `buildInADO` function to authenticate with the Azure DevOps API.
+- **PULL_NUMBER**: The number of the PR.
+- **PULL_BASE_SHA**: The base SHA of the PR or push commit SHA.
+- **PULL_PULL_SHA**: The PR head SHA of the PR.
+- **ADO_PAT**: The Azure DevOps Personal Access Token. It's used in the `buildInADO` function to authenticate with the ADO API.
 - **USE_BUILDKIT**: Determines whether to use BuildKit for building the image. A `buildkit-image-builder` image has this variable set
   to `true` by default.
 - **CI**: Determines whether the image builder runs in CI mode.
@@ -152,9 +152,9 @@ sign-config:
 ```
 
 All enabled signers under `'*'` are used globally. Additionally, if a repository contains another signer configuration
-in the `org/repo` key, Image Builder also uses this service to sign the image.
-If the job is running in CI (Prow), it picks up the current `org/repo` value from the default Prow variables. If binary
-is running outside of CI, `--repo` flag will have to be used. Otherwise, the configuration will not be used.
+in the **org/repo** key, Image Builder also uses this service to sign the image.
+If the job is running in CI (Prow), it picks up the current **org/repo** value from the default Prow variables. If binary
+is running outside of CI, the `--repo` flag must be used. Otherwise, the configuration will not be used.
 
 Currently, Image Builder contains a basic implementation of a notary signer. If you want to add a new signer, refer to
 the [`sign`](../../pkg/sign) package, and its code.
@@ -186,9 +186,9 @@ Image Builder supports three build backends:
 
 - kaniko
 - BuildKit
-- Azure DevOps pipelines
+- ADO pipelines
 
-kaniko and BuildKit build images locally while the Azure DevOps pipelines backend call ADO API.
+kaniko and BuildKit build images locally, while for the ADO pipelines backend, Image Builder calls ADO API to start the build process.
 To use the kaniko backend, use the `image-builder` image.
 To use the BuildKit backend, use the `buildkit-image-builder` image.
 The ADO backend is supported by both images. To use it, you need to provide the `--build-in-ado=true` flag.
@@ -197,7 +197,7 @@ The preferred way to build images is to use the ADO backend because it's the onl
 
 ### Azure DevOps Backend (ADO)
 
-The ADO backend uses Image Builder to call ADO API and trigger the `oci-image-builder` pipeline. This backend is SLC-29 compliant. It supports signing images with a production signify service. Images built with ADO can be pushed into Kyma GCP artifacts registries. To build images, the ADO backend uses the `kaniko-project/executor` image. 
+The ADO backend uses Image Builder to call ADO API and trigger the `oci-image-builder` pipeline. This backend is SLC-29 compliant. It supports signing images with a production signify service. Images built with ADO can be pushed into Kyma Google Cloud artifacts registries. To build images, the ADO backend uses the `kaniko-project/executor` image. 
 This backend doesn't support the `--env-file`, `--platform`, and `--variant` flags. Building images for platforms other than amd64 is not supported. 
 To use this backend, you need to use Image Builder in a ProwJob. See [Quickstart Guide](#quickstart-guide) for an example ProwJob definition.
 
@@ -213,7 +213,8 @@ To specify a path to the YAML file with the pipeline definition, use the `--ado-
 
 ### Build Multi-Architecture Images
 
-> **NOTE:** This is an experimental feature that may change in the future.
+> [!WARNING] 
+> This is an experimental feature that may change in the future.
 
 With the introduction of the experimental BuildKit support, the tool now supports the repeatable flag `--platform`.
 You can define multiple platforms you want to build an image for.
@@ -245,5 +246,5 @@ To use this feature, make sure that:
 
 ### Environment Variables File
 
-`-env-file` specifies the path to the file with environment variables to be loaded in the build. This flag is deprecated.
+The `-env-file` specifies the path to the file with environment variables to be loaded in the build. This flag is deprecated.
 Use `--build-arg` instead.

cmd/image-builder/github-workflow-integration.md

@@ -52,34 +52,34 @@ The OIDC token contains the following claims that can be used to identify the wo
 
 <!-- markdown-link-check-disable -->
 
-- `iss`: The issuer of the token. This is always https://token.actions.githubusercontent.com. <!-- markdown-link-check-enable-->
-- `iat`: The time when the token is issued.
-- `exp`: The time when the token expires.
-- `jti`: A unique identifier for the token.
-- `nbf`: The time before which the token must not be accepted for processing.
-- `kid`: The key ID of the key used to sign the token.
-- `alg`: The algorithm used to sign the token.
-- `run_id`: The ID of the workflow run.
-- `run_number`: The number of the workflow run.
-- `actor`: The login of the user who initiates the workflow run.
-- `event_name`: The name of the event that triggers the workflow run.
-- `workflow`: The name of the workflow that triggers the workflow run.
-- `workflow_ref`: The git ref associated with the workflow file.
-- `repository`: The repository where the workflow run occurs.
-- `repository_owner`: The owner of the repository where the workflow run occurs.
+- **iss**: The issuer of the token. This is always https://token.actions.githubusercontent.com. <!-- markdown-link-check-enable-->
+- **iat**: The time when the token is issued.
+- **exp**: The time when the token expires.
+- **jti**: A unique identifier for the token.
+- **nbf**: The time before which the token must not be accepted for processing.
+- **kid**: The key ID of the key used to sign the token.
+- **alg**: The algorithm used to sign the token.
+- **run_id**: The ID of the workflow run.
+- **run_number**: The number of the workflow run.
+- **actor**: The login of the user who initiates the workflow run.
+- **event_name**: The name of the event that triggers the workflow run.
+- **workflow**: The name of the workflow that triggers the workflow run.
+- **workflow_ref**: The git ref associated with the workflow file.
+- **repository**: The repository where the workflow run occurs.
+- **repository_owner**: The owner of the repository where the workflow run occurs.
 
 ### Source Code Cloning Claims
 
 The OIDC token also contains claims that can be used to clone the appropriate version of the source code:
 
-- `repository`: The repository where the workflow run occurs.
-- `repository_owner`: The owner of the repository where the workflow run occurs.
-- `event_name`: The name of the event that triggers the workflow run.
-- `ref`: The git ref associated with the workflow run. This can be used to checkout the correct branch, tag, or commit.
-- `ref_type`: The type of git ref associated with the workflow run. This can be used to determine whether the ref is a branch, tag, or
+- **repository**: The repository where the workflow run occurs.
+- **repository_owner**: The owner of the repository where the workflow run occurs.
+- **event_name**: The name of the event that triggers the workflow run.
+- **ref**: The git ref associated with the workflow run. This can be used to checkout the correct branch, tag, or commit.
+- **ref_type**: The type of git ref associated with the workflow run. This can be used to determine whether the ref is a branch, tag, or
   commit.
-- `base_ref`: The base git ref associated with the workflow run. This can be used to determine the base branch for a pull request.
-- `head_ref`: The head git ref associated with the workflow run. This can be used to determine the head branch for a pull request.
+- **base_ref**: The base git ref associated with the workflow run. This can be used to determine the base branch for a pull request.
+- **head_ref**: The head git ref associated with the workflow run. This can be used to determine the head branch for a pull request.
 
 These claims ensure that the `oci-image-builder` pipeline builds the exact version of the code that was provided in the PR or merged to the
 branch, adhering to SLC-29 compliance.

cmd/image-url-helper/README.md

@@ -52,7 +52,7 @@ go run main.go \
     --dry-run=false
 ```
 
-### Exclude images from the check command
+### Exclude Images from the Check Command
 
 To exclude image lines from being checked, create a YAML file that contains a list of files and values of images that you want to exclude from the check. Then, provide a path to this file in the `check` command argument. See the example of such a YAML file:
 
@@ -67,7 +67,7 @@ excludes:
       - "{{ .Values.imageRenderer.image.repository }}:{{ .Values.imageRenderer.image.tag }}"
 ```
 
-### Check command flags
+### Check Command Flags
 
 See the list of flags available for the `check` command:
 
@@ -77,7 +77,7 @@ See the list of flags available for the `check` command:
 | **--skip-comments**       |    No    | Skip commented out lines.             |
 | **--excludes-list**       |    No    | Path to the list of excluded images.  |
 
-### List command flags
+### List Command Flags
 
 See the list of flags available for the `list` and `missing` command: