From 6f969214d31b3dc700e390d22266b3f62c5bb24e Mon Sep 17 00:00:00 2001
From: Katie Horne <katie@coder.com>
Date: Thu, 19 May 2022 08:01:19 -0500
Subject: [PATCH] chore: validate docs (#1485)

---
 docs/README.md     | 69 +++++++++++++++++++++++++++++-----------------
 docs/templates.md  |  2 +-
 docs/workspaces.md |  7 ++---
 3 files changed, 47 insertions(+), 31 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index e893b76523..8cabf3cb38 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -20,52 +20,69 @@ Provision remote development environments with Terraform.
 
 ## Installing Coder
 
-Install [the latest release](https://github.com/coder/coder/releases) on a system with
-at least 1 CPU core and 2 GB RAM.
+We recommend installing [the latest
+release](https://github.com/coder/coder/releases) on a system with at least 1
+CPU core and 2 GB RAM:
 
-To test, start with dev mode (all data is in-memory and is destroyed on exit):
+1. Download the release appropriate for your operating system
+1. Unzip the folder you just downloaded, and move the `coder` executable to a
+   location that's on your `PATH`
 
-```bash
-coder server --dev
-```
+> Make sure you have the appropriate credentials for your cloud provider (e.g.,
+> access key ID and secret access key for AWS).
 
-To run a production deployment with PostgreSQL:
+You can set up a temporary deployment, a production deployment, or a system service:
 
-```bash
-CODER_PG_CONNECTION_URL="postgres://<username>@<host>/<database>?password=<password>" \
-    coder server
-```
+- To set up a **temporary deployment**, start with dev mode (all data is in-memory and is
+destroyed on exit):
 
-To run as a system service, install with `.deb` (Debian, Ubuntu) or `.rpm`
+  ```bash
+  coder server --dev
+  ```
+
+- To run a **production deployment** with PostgreSQL:
+
+  ```bash
+  CODER_PG_CONNECTION_URL="postgres://<username>@<host>/<database>?password=<password>" \
+      coder server
+  ```
+
+- To run as a **system service**, install with `.deb` (Debian, Ubuntu) or `.rpm`
 (Fedora, CentOS, RHEL, SUSE):
 
-```bash
-# Edit the configuration!
-sudo vim /etc/coder.d/coder.env
-sudo service coder restart
-```
+  ```bash
+  # Edit the configuration!
+  sudo vim /etc/coder.d/coder.env
+  sudo service coder restart
+  ```
 
-Use `coder start --help` to get a complete list of flags and environment
+> Use `coder --help` to get a complete list of flags and environment
 variables.
 
-### Your first workspace
+## Creating your first template and workspace
 
-In a new terminal, create a template (e.g., a template to **Develop in Linux on
-Google Cloud**):
+In a new terminal window, run the following to copy a sample template:
 
 ```bash
 coder templates init
-coder templates create
 ```
 
-Create a workspace and connect to it via SSH:
+Follow the CLI instructions to modify and create the template specific for your
+usage (e.g., a template to **Develop in Linux on Google Cloud**).
+
+Create a workspace using your template:
 
 ```bash
-coder create my-first-workspace
-coder ssh my-first-workspace
+coder create --template="yourTemplate" <workspaceName>
 ```
 
-### Modifying templates
+Connect to your workspace via SSH:
+
+```bash
+coder ssh <workspaceName>
+```
+
+## Modifying templates
 
 You can edit the Terraform template using a sample template:
 
diff --git a/docs/templates.md b/docs/templates.md
index 14bc39726c..912dffc08b 100644
--- a/docs/templates.md
+++ b/docs/templates.md
@@ -9,7 +9,7 @@ to everybody. Users can also manually update their workspaces.
 
 ## Manage templates
 
-Coder provides production-ready [sample template](../examples/), but you can
+Coder provides production-ready [sample templates](../examples/), but you can
 modify the templates with Terraform.
 
 ```sh
diff --git a/docs/workspaces.md b/docs/workspaces.md
index 4bb0723e30..0dbdd0862f 100644
--- a/docs/workspaces.md
+++ b/docs/workspaces.md
@@ -12,7 +12,7 @@ templates](./templates.md):
 # create a workspace from the template; specify any variables
 coder create <workspace-name>
 
-# show the resources behind the workspace, and how to connect
+# show the resources behind the workspace and how to connect
 coder show <workspace-name>
 ```
 
@@ -23,8 +23,7 @@ IDE with remote development support:
 
 ```sh
 coder config-ssh
-
-ssh coder.<workspace-name>
+coder ssh <workspaceName>
 ```
 
 ## Editors and IDEs
@@ -61,7 +60,7 @@ resources](./templates.md#persistent-and-ephemeral-resources).
 > where to store files, install software, etc., so that they persist. Default
 > templates are documented in [../examples](../examples/).
 >
-> You can use `coder workspace show <workspace-name>` to see which resources are
+> You can use `coder show <workspace-name>` to see which resources are
 > persistent and which are ephemeral.
 
 When a workspace is deleted, all of the workspace's resources are deleted.