Refactor GitLab basics ssh keys docsdocs/overhaul-create-ssh-keys-page

Ensures we give instructions for how to create ssh keys
in a single place only.

4 files changed, 26 insertions, 25 deletions

diff --git a/doc/gitlab-basics/README.md b/doc/gitlab-basics/README.md
index 28ba20bec09..00ac6d6b650 100644
--- a/doc/gitlab-basics/README.md
+++ b/doc/gitlab-basics/README.md
@@ -15,7 +15,7 @@ This documentation is split into the following groups:
 
 The following are guides to basic GitLab functionality:
 
-- [Create and add your SSH Keys](create-your-ssh-keys.md), for enabling Git over SSH.
+- [Create and add your SSH public key](create-your-ssh-keys.md), for enabling Git over SSH.
 - [Create a project](create-project.md), to start using GitLab.
 - [Create a group](../user/group/index.md#create-a-new-group), to combine and administer projects together.
 - [Create a branch](create-branch.md), to make changes to files stored in a project's repository.
diff --git a/doc/gitlab-basics/create-your-ssh-keys.md b/doc/gitlab-basics/create-your-ssh-keys.md
index 8fecdc6948e..aac73d4c9c5 100644
--- a/doc/gitlab-basics/create-your-ssh-keys.md
+++ b/doc/gitlab-basics/create-your-ssh-keys.md
@@ -1,22 +1,22 @@
-# How to create your SSH keys
+# Create and add your SSH public key
 
-This topic describes how to create SSH keys. You do this to use Git over SSH instead of Git over HTTP.
+This topic describes how to:
 
-## Creating your SSH keys
+- Create an SSH key pair to use with GitLab.
+- Add the SSH public key to your GitLab account.
 
-1. Go to your [command line](start-using-git.md) and follow the [instructions](../ssh/README.md) to generate your SSH key pair.
-1. Log in to GitLab.
-1. In the upper-right corner, click your avatar and select **Settings**.
-1. On the **User Settings** menu, select **SSH keys**.
-1. Paste the **public** key generated in the first step in the **Key**
-   text field.
-1. Optionally, give it a descriptive title so that you can recognize it in the
-   event you add multiple keys.
-1. Finally, click the **Add key** button to add it to GitLab. You will be able to see
-   its fingerprint, title, and creation date.
+You do this to use [Git over SSH instead of Git over HTTP](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols).
 
-    ![SSH key single page](img/profile_settings_ssh_keys_single_key.png)
+## Creating your SSH key pair
+
+1. Go to your [command line](start-using-git.md).
+1. Follow the [instructions](../ssh/README.md#generating-a-new-ssh-key-pair) to generate your SSH key pair.
+
+## Adding your SSH public key to GitLab
+
+To add the SSH public key to GitLab,
+see [Adding an SSH key to your GitLab account](../ssh/README.md#adding-an-ssh-key-to-your-gitlab-account).
 
 NOTE: **Note:**
 Once you add a key, you cannot edit it. If the paste
-didn't work, you need  to remove the offending key and re-add it.
+[didn't work](../ssh/README.md#testing-that-everything-is-set-up-correctly), you need to remove the key and re-add it.
diff --git a/doc/gitlab-basics/img/profile_settings_ssh_keys_single_key.png b/doc/gitlab-basics/img/profile_settings_ssh_keys_single_key.png
deleted file mode 100644
index 8014f1d5301..00000000000
--- a/doc/gitlab-basics/img/profile_settings_ssh_keys_single_key.png
+++ /dev/null
diff --git a/doc/ssh/README.md b/doc/ssh/README.md
index 9c4a391e8da..3bfebfc5d9b 100644
--- a/doc/ssh/README.md
+++ b/doc/ssh/README.md
@@ -55,7 +55,7 @@ As an admin, you can restrict
 By default, all keys are permitted, which is also the case for
 [GitLab.com](../user/gitlab_com/index.md#ssh-host-keys-fingerprints).
 
-## ED25519 SSH keys
+### ED25519 SSH keys
 
 Following [best practices](https://linux-audit.com/using-ed25519-openssh-keys-instead-of-dsa-rsa-ecdsa/),
 you should always favor [ED25519](https://ed25519.cr.yp.to/) SSH keys, since they
@@ -65,7 +65,7 @@ They were introduced in OpenSSH 6.5, so any modern OS should include the
 option to create them. If for any reason your OS or the GitLab instance you
 interact with doesn't support this, you can fallback to RSA.
 
-## RSA SSH keys
+### RSA SSH keys
 
 RSA keys are the most common ones and therefore the most compatible with
 servers that may have an old OpenSSH version. Use them if the GitLab server
@@ -166,12 +166,13 @@ Now, it's time to add the newly created public key to your GitLab account.
     NOTE: **Note:**
     If you opted to create an RSA key, the name might differ.
 
-1. Add your public SSH key to your GitLab account by clicking your avatar
-   in the upper right corner and selecting **Settings**. From there on,
-   navigate to **SSH Keys** and paste your public key in the "Key" section.
-   If you created the key with a comment, this will appear under "Title".
-   If not, give your key an identifiable title like _Work Laptop_ or
-   _Home Workstation_, and click **Add key**.
+1. Add your **public** SSH key to your GitLab account by:
+   1. Clicking your avatar in the upper right corner and selecting **Settings**.
+   1. Navigating to **SSH Keys** and pasting your **public** key in the **Key** field. If you:
+
+      - Created the key with a comment, this will appear in the **Title** field.
+      - Created the key without a comment, give your key an identifiable title like _Work Laptop_ or _Home Workstation_.
+   1. Click the **Add key** button.
 
     NOTE: **Note:**
     If you manually copied your public SSH key make sure you copied the entire
@@ -305,7 +306,7 @@ who needs to know and configure the private key.
 GitLab administrators set up Global Deploy keys in the Admin area under the
 section **Deploy Keys**. Ensure keys have a meaningful title as that will be
 the primary way for project maintainers and owners to identify the correct Global
-Deploy key to add.  For instance, if the key gives access to a SaaS CI instance,
+Deploy key to add. For instance, if the key gives access to a SaaS CI instance,
 use the name of that service in the key name if that is all it is used for.
 When creating Global Shared Deploy keys, give some thought to the granularity
 of keys - they could be of very narrow usage such as just a specific service or