GitLab basics overhaul: how to create your ssh keys
From @rdickenson's video teardown (https://www.youtube.com/watch?v=P4yaGtPrJrg) of https://docs.gitlab.com/11.10/ee/gitlab-basics/create-your-ssh-keys.html, improve the how to create your SSH keys page using the following notes:
- Title on landing page doesn't match the title of the document.
- Elsewhere we say Git over SSH is preferred, without saying why. In this document, we also don't say why.
- We might be able to assume the reader knows they want SSH keys, and don't need to discuss what it's for.
- The procedure is about "creating SSH keys", but then we talk about GitLab, which isn't used to create them.
- The provided instructions (in a link) don't link to instructions for creating the keys, but starts at a point of more general documentation.
- The linked-to instructions are duplicative, in that they also give information on Adding an SSH key to your GitLab account.
- The provided note doesn't really say how you can know if the key does or doesn't work.
Suggestions:
-
Perhaps this is really for adding SSH keys to GitLab. -
Link directly to section of GitLab and SSH keys
calledGenerating a new SSH key pair
. -
As a single source of truth, this page and https://docs.gitlab.com/ee/ssh/README.html shouldn't duplicate information. -
Wherever the information is kept, the instructions should be broken down to make them more readable. -
In the note, link to verification steps in https://docs.gitlab.com/ee/ssh/README.html#testing-that-everything-is-set-up-correctly.
Note: I haven't included some points made about the GitLab and SSH keys page as they are out of scope.
@rdickenson anything to add?
CC @gl-docsteam.
Edited by Evan Read