From db17b384f77230b13c871544b891b875b947c67a Mon Sep 17 00:00:00 2001
From: Jorge Orpinel Perez <jorge@orpinel.com>
Date: Sun, 12 Mar 2023 10:36:10 -0600
Subject: [PATCH] guide: start improving SSH remote page

---
 content/docs/sidebar.json                     |  2 +-
 .../data-management/remote-storage/index.md   |  4 ++--
 .../data-management/remote-storage/ssh.md     | 24 +++++++++++++++----
 3 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/content/docs/sidebar.json b/content/docs/sidebar.json
index 9f5d06aa6ff..799851280a4 100644
--- a/content/docs/sidebar.json
+++ b/content/docs/sidebar.json
@@ -137,7 +137,7 @@
                 "slug": "aliyun-oss"
               },
               {
-                "label": "SSH",
+                "label": "SSH & SFTP",
                 "slug": "ssh"
               },
               {
diff --git a/content/docs/user-guide/data-management/remote-storage/index.md b/content/docs/user-guide/data-management/remote-storage/index.md
index 67f5f011297..af1dc169b13 100644
--- a/content/docs/user-guide/data-management/remote-storage/index.md
+++ b/content/docs/user-guide/data-management/remote-storage/index.md
@@ -112,7 +112,7 @@ team.
 
 ### Self-hosted / On-premises
 
-- [SSH]; Like `scp`
+- [SSH] & SFTP (like `scp`)
 - [HDFS] & [WebHDFS]
 - [HTTP]
 - [WebDAV]
@@ -125,7 +125,7 @@ team.
 
 ## File systems (local remotes)
 
-<admon type="tip">
+<admon type="info">
 
 Not related to the `--local` option of `dvc remote` and `dvc config`!
 
diff --git a/content/docs/user-guide/data-management/remote-storage/ssh.md b/content/docs/user-guide/data-management/remote-storage/ssh.md
index 32855b2d9ab..65eab53622a 100644
--- a/content/docs/user-guide/data-management/remote-storage/ssh.md
+++ b/content/docs/user-guide/data-management/remote-storage/ssh.md
@@ -1,20 +1,34 @@
-# SSH
+# SSH and SFTP
 
 <!--
 ## SSH
 -->
 
+[SSH] (Secure Shell) is a protocol to connect to a remote computer, which lets
+you transfer files to and from a remote machine using encryption (like [`scp`])
+among other features. DVC will act as an SSH client (like [`ssh`]) which means
+that the remote storage should be in an [SSH server]. The credentials to
+establish the connection (username, password or private key, etc.) are usually
+set in [SSH configuration]; SSH remotes in DVC accept the same values.
+
+[SSH]: https://www.ssh.com/academy/ssh
+[`scp`]: https://www.ssh.com/academy/ssh/scp
+[`ssh`]: https://www.ssh.com/academy/ssh/command
+[ssh server]: https://www.ssh.com/academy/ssh/server
+[ssh configuration]: https://www.ssh.com/academy/ssh/config
+
 Start with `dvc remote add` to define the remote:
 
 ```cli
 $ dvc remote add -d myremote ssh://user@example.com/path
 ```
 
-⚠️ DVC requires both SSH and SFTP access to work with remote SSH locations.
-Check that you can connect both ways with tools like `ssh` and `sftp`
-(GNU/Linux).
+<admon type="warn">
+
+DVC requires both SSH and SFTP access to work with remote SSH locations. Check
+that you can connect both ways with tools like `ssh` and `sftp` (GNU/Linux).
 
-> Note that the server's SFTP root might differ from its physical root (`/`).
+</admon>
 
 ## Configuration parameters