Merge branch 'deploy-keys-docs-vale-339539' into 'master'

Deploy key docs Vale fixes and refactors

See merge request gitlab-org/gitlab!69485

doc/user/project/deploy_keys/index.md

@@ -10,9 +10,10 @@ type: howto, reference
 Deploy keys allow read-only or read-write access to your
 repositories by importing an SSH public key into your GitLab instance.
 
-This is useful, for example, for cloning repositories to your Continuous
-Integration (CI) server. By using deploy keys, you don't have to set up a
-fake user account.
+Deploy keys streamline interactions between your GitLab repository and another
+machine. For example, setting up a deploy key allows secure cloning of your
+repositories to a Continuous Integration (CI) server without setting up a fake
+user account.
 
 There are two types of deploy keys:
 
@@ -63,11 +64,12 @@ help you access a repository, but there are some notables differences between th
 - Deploy keys are shareable between projects that are not related or don't even
   belong to the same group. Deploy tokens belong to either a project or
   [a group](../deploy_tokens/index.md#group-deploy-token).
-- A deploy key is an SSH key you need to generate yourself on your machine. A deploy
-  token is generated by your GitLab instance, and is provided to users only once
-  (at creation time).
-- A deploy key is valid as long as it's registered and enabled. Deploy tokens can
-  be time-sensitive, as you can control their validity by setting an expiration date to them.
+- A deploy key is an SSH key you generate on the **remote machine**. A deploy
+  token, on the other hand, is generated by your **GitLab instance**, and is
+  provided to users only once (at creation time).
+- A deploy key is valid as long as it's registered and enabled. Deploy tokens
+  can be time-sensitive, as you can control their validity by setting an
+  expiration date to them.
 - You can't log in to a registry with deploy keys, or perform read / write operations
   on it, but this [is possible with deploy tokens](../deploy_tokens/index.md#gitlab-deploy-token).
 - You need an SSH key pair to use deploy keys, but not deploy tokens.
@@ -115,9 +117,9 @@ project, and if you then update the access level for this key from `read-only` t
 
 ### Public deploy keys
 
-Public deploy keys allow `read-only` or `read-write`
-access to any repository in your GitLab instance. This is useful for integrating
-repositories to secure, shared services, such as CI/CD.
+Public deploy keys allow `read-only` or `read-write` access to any repository in
+your GitLab instance. This allows for the integration of your repositories to
+secure, shared services, such as CI/CD.
 
 Instance administrators can add public deploy keys:
 
@@ -125,32 +127,37 @@ Instance administrators can add public deploy keys:
 1. On the left sidebar, select **Deploy Keys**.
 1. Select **New deploy key**.
 
-   Make sure your new key has a meaningful title, as it is the primary way for project
-   maintainers and owners to identify the correct public deploy key to add. For example,
-   if the key gives access to a SaaS CI/CD instance, use the name of that service
-   in the key name if that is all the key is used for.
+Make sure your new key has a meaningful title. This title is the primary
+way for project maintainers and owners to identify the correct public deploy key
+to add to a repository or project. For example, the key you set up might be
+intended to give access to a SaaS CI/CD instance. In this case use the name of
+that service in the key title if that is all the key is used for.
 
 ![Public deploy keys section](img/public_deploy_key_v13_0.png)
 
-After adding a key, it's available to any shared systems. Project maintainers
-or higher can [authorize a public deploy key](#project-deploy-keys) to start using it with the project.
+After adding a key, it's available to any shared system. Users with a maintainer role or
+higher can [authorize a public deploy key](#project-deploy-keys) to start using
+it with the project.
 
 NOTE:
-The **Publicly accessible deploy keys** tab within Project's CI/CD settings only appears
-if there is at least one Public deploy key configured.
+The **Publicly accessible deploy keys** tab in a Project's CI/CD
+settings only appears if there is at least one Public deploy key configured.
 
-Public deploy keys can provide greater security compared to project deploy keys, as
-the administrator of the target integrated system is the only one who needs to know the key value,
-or configure it.
+Public deploy keys can provide greater security compared to project deploy keys.
+This is because the administrator of the target integrated system is the only
+entity who needs to know or configure the key value.
 
-When creating a Public deploy key, determine whether or not it can be defined for
-very narrow usage, such as just a specific service, or if it needs to be defined for
-broader usage, such as full `read-write` access for all services.
+When creating a Public deploy key, consider what scope and permissions are
+required for it across the entire GitLab instance. For very narrow usage, such
+as a single specific service, a `read-only` deploy key tied to this service is
+best. If the service entails broader usage across the instance, a
+deploy key with full `read-write` access is more appropriate.
 
 WARNING:
-Adding a public deploy key does not immediately expose any repository to it. Public
-deploy keys enable access from other systems, but access is not given to any project
-until a project maintainer chooses to make use of it.
+Adding a public deploy key **does not** immediately expose any repository
+to the remote machine. Access to a project is only given when a project
+maintainer chooses to make use of a deploy key in the project's
+configuration.
 
 ## How to disable deploy keys
 
@@ -162,13 +169,17 @@ can remove or disable a deploy key for a project repository:
 1. Select the **{remove}** or **{cancel}** button.
 
 NOTE:
-If anything relies on the removed deploy key, it will stop working once removed.
+Any service that relies on a deploy key stops working after that key is removed.
 
-If the key is **publicly accessible**, it will be removed from the project, but still available under **Publicly accessible deploy keys**.
+If the key is **publicly accessible**, it is removed from the project, but can
+still be found under **Publicly accessible deploy keys**.
 
-If the key is **privately accessible** and only in use by this project, it will deleted.
+If the key is **privately accessible** and only in use by this project, it is
+deleted entirely from GitLab on removal.
 
-If the key is **privately accessible** and in use by other projects, it will be removed from the project, but still available under **Privately accessible deploy keys**.
+If the key is **privately accessible** and also in use by other projects, it is
+removed from the project, but still available under **Privately accessible
+deploy keys**.
 
 ## Troubleshooting