From 9fd1462523662e969ce3a38ff9d8a5609a968531 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 (intro)

---
 content/docs/sidebar.json                     |  2 +-
 .../importing-external-data.md                | 10 +++--
 .../data-management/managing-external-data.md | 10 +++--
 .../data-management/remote-storage/index.md   |  4 +-
 .../data-management/remote-storage/ssh.md     | 37 ++++++++++++++++---
 5 files changed, 46 insertions(+), 17 deletions(-)

diff --git a/content/docs/sidebar.json b/content/docs/sidebar.json
index 9f5d06aa6f..799851280a 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/importing-external-data.md b/content/docs/user-guide/data-management/importing-external-data.md
index 37bf226da3..3d680bf677 100644
--- a/content/docs/user-guide/data-management/importing-external-data.md
+++ b/content/docs/user-guide/data-management/importing-external-data.md
@@ -99,11 +99,13 @@ $ dvc stage add -n download_file \
           scp user@example.com:/path/to/data.txt data.txt
 ```
 
-⚠️ 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">
 
-> Note that your server's SFTP root might differ from its physical root (`/`).
+DVC requires both SSH and SFTP access to work with SSH remote storage. Check
+that you can connect both ways with tools like `ssh` and `sftp` (GNU/Linux).  
+Note that your server's SFTP root might differ from its physical root (`/`).
+
+</admon>
 
 </details>
 
diff --git a/content/docs/user-guide/data-management/managing-external-data.md b/content/docs/user-guide/data-management/managing-external-data.md
index f33918e7d4..666ce04fe3 100644
--- a/content/docs/user-guide/data-management/managing-external-data.md
+++ b/content/docs/user-guide/data-management/managing-external-data.md
@@ -125,11 +125,13 @@ $ dvc stage add -d data.txt \
           scp data.txt user@example.com:/data.txt
 ```
 
-⚠️ 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">
 
-> Note that your server's SFTP root might differ from its physical root (`/`).
+DVC requires both SSH and SFTP access to work with SSH remote storage. Check
+that you can connect both ways with tools like `ssh` and `sftp` (GNU/Linux).  
+Note that your server's SFTP root might differ from its physical root (`/`).
+
+</admon>
 
 </details>
 
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 67f5f01129..af1dc169b1 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 32855b2d9a..e4a4f7ed52 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,45 @@
-# SSH
+# SSH and SFTP
 
 <!--
 ## SSH
 -->
 
-Start with `dvc remote add` to define the remote:
+<details>
+
+### Click to learn about SSH and SFTP.
+
+[SSH] (Secure Shell) is a protocol that uses encryption to secure a connection
+with a remote computer, which lets you safely transfer files to and from it
+(like [`scp`]), among other features. Other operations can be used on top of
+SSH, like FTP (simple file transfer protocol) which becomes secure or [SFTP].
+
+[SSH]: https://www.ssh.com/academy/ssh
+[SFTP]: https://www.ssh.com/academy/ssh/sftp-ssh-file-transfer-protocol
+[`scp`]: https://www.ssh.com/academy/ssh/scp
+
+</details>
+
+DVC will act as an SSH/SFTP client, which means that the remote storage should
+be located in an [SSH server]. Use `dvc remote add` to define the remote by
+setting a name and valid [SSH URL] (may include basic auth info. like a user
+name):
 
 ```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).
+[ssh server]: https://www.ssh.com/academy/ssh/server
+[SSH URL]: https://www.ietf.org/archive/id/draft-salowey-secsh-uri-00.html
+
+<admon type="warn">
+
+DVC requires both SSH and SFTP access to work with SSH remote storage. Check
+that you can connect both ways with tools like [`ssh`] and `sftp` (GNU/Linux).  
+Note that your server's SFTP root might differ from its physical root (`/`).
+
+[`ssh`]: https://www.ssh.com/academy/ssh/command
 
-> Note that the server's SFTP root might differ from its physical root (`/`).
+</admon>
 
 ## Configuration parameters