From 1b97eaa7247a7c7749357b7abd684b376ce89157 Mon Sep 17 00:00:00 2001
From: Amy Qualls <aqualls@gitlab.com>
Date: Tue, 15 Feb 2022 07:49:30 -0800
Subject: Revisions for tone and style

Do an initial cleanup pass:

- Line wraps
- Change 'allows' to 'enables'
- Clean up syntax highlighting
- Fix spelling and capitalization
- Standardize on colons at the end of the introductory sentences
---
 doc/features.md | 50 +++++++++++++++++++++++++++++++-------------------
 1 file changed, 31 insertions(+), 19 deletions(-)

diff --git a/doc/features.md b/doc/features.md
index bbd6b7d..21ee918 100644
--- a/doc/features.md
+++ b/doc/features.md
@@ -1,8 +1,11 @@
-### Discover
+# Feature list
 
-Allows users to identify themselves on an instance via SSH. The command is useful for checking out quickly whether a user has SSH access to the instance:
+## Discover
 
-```bash
+Allows users to identify themselves on an instance via SSH. The command helps to
+confirm quickly whether a user has SSH access to the instance:
+
+```shell
 ssh git@<hostname>
 
 PTY allocation request failed on channel 0
@@ -10,22 +13,30 @@ Welcome to GitLab, @username!
 Connection to staging.gitlab.com closed.
 ```
 
-When permission is denied:
+When permission is denied, it returns:
 
-```bash
+```shell
 ssh git@<hostname>
 git@<hostname>: Permission denied (publickey).
 ```
 
-### Git operations
+## Git operations
+
+GitLab Shell provides support for Git operations over SSH by processing
+`git-upload-pack`, `git-receive-pack` and `git-upload-archive` SSH commands.
+It limits the set of commands to predefined Git commands:
 
-Gitlab Shell provides support for Git operations over SSH via processing `git-upload-pack`, `git-receive-pack` and `git-upload-archive` SSH commands. It limit the set of commands to predefined git commands (git push, git clone/pull, git archive).
+- `git archive`
+- `git clone`
+- `git pull`
+- `git push`
 
-### Generate new 2FA recovery codes
+## Generate new 2FA recovery codes
 
-Allows users to [generate new 2FA recovery codes](https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication.html#generate-new-recovery-codes-using-ssh).
+Enables users to
+[generate new 2FA recovery codes](https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication.html#generate-new-recovery-codes-using-ssh):
 
-```bash
+```plaintext
 ssh git@<hostname> 2fa_recovery_codes
 Are you sure you want to generate new two-factor recovery codes?
 Any existing recovery codes you saved will be invalidated. (yes/no)
@@ -35,32 +46,33 @@ Your two-factor authentication recovery codes are:
 ...
 ```
 
-### Verify 2FA OTP
+## Verify 2FA OTP
 
-Allows users to [verify their 2FA OTP](https://docs.gitlab.com/ee/security/two_factor_authentication.html#2fa-for-git-over-ssh-operations).
+Allows users to verify their
+[2FA one-time password (OTP)](https://docs.gitlab.com/ee/security/two_factor_authentication.html#2fa-for-git-over-ssh-operations):
 
-```bash
+```shell
 ssh git@<hostname> 2fa_verify
 OTP: 347419
 
 OTP validation failed.
 ```
 
-### LFS authentication
+## LFS authentication
 
-Allows users to generate credentials for LFS authentication.
+Enables users to generate credentials for LFS authentication:
 
-```bash
+```shell
 ssh git@<hostname> git-lfs-authenticate <project-path> <upload/download>
 
 {"header":{"Authorization":"Basic ..."},"href":"https://gitlab.com/user/project.git/info/lfs","expires_in":7200}
 ```
 
-### Personal access token
+## Personal access token
 
-Allows users to personal access tokens via SSH
+Enables users to use personal access tokens via SSH:
 
-```bash
+```shell
 ssh git@<hostname> personal_access_token <name> <scope1[,scope2,...]> [ttl_days]
 
 Token:   glpat-...
-- 
cgit v1.2.1