coder · khorne3 · Jun 16, 2022 · Jun 15, 2022 · Jun 15, 2022 · Jun 15, 2022
diff --git a/docs/ides.md b/docs/ides.md
@@ -0,0 +1,144 @@
+# IDEs
+
+The following desktop IDEs have been tested with Coder, though any IDE with SSH
+support should work:
+
+- VS Code (with [Remote -
+  SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)
+  extension)
+- JetBrains (with
+  [Gateway](https://www.jetbrains.com/help/idea/remote-development-a.html#launch_gateway)
+  installed)
+  - IntelliJ IDEA
+  - CLion
+  - GoLand
+  - PyCharm
+  - Rider
+  - RubyMine
+  - WebStorm
+
+## SSH configuration
+
+> Before proceeding, run `coder login <accessURL>` if you haven't already to
+> authenticate the CLI with the web UI and your workspaces.
+
+To access Coder via SSH, run the following in the terminal:
+
+```console
+coder config-ssh
+```
+
+> Run `coder config-ssh --diff` if you'd like to see the changes that will be
+> made before proceeding.
+
+Confirm that you want to continue by typing **yes** and pressing enter. If
+successful, you'll see the following message:
+
+```console
+You should now be able to ssh into your workspace.
+For example, try running:
+
+$ ssh coder.<workspaceName>
+```
+
+Your workspace is now accessible via `ssh coder.<workspace_name>` (e.g.,
+`ssh coder.myEnv` if your workspace is named `myEnv`).
+
+## VS Code Remote
+
+Once you've configured SSH, you can work on projects from your local copy of VS
+Code, connected to your Coder workspace for compute, etc.
+
+1. Open VS Code locally.
+
+1. Install the [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)
+   extension.
+
+1. In VS Code's left-hand nav bar, click **Remote Explorer** and right-click on
+   a workspace to connect.
+
+## VS Code in the browser
+
+> You must have Docker Desktop running for this template to work.
+
+Coder offers a [sample template that includes
+code-server](../examples/templates/docker-code-server/README.md).
+
+To use:
+
+1. Start Coder:
+
+  ```console
+  coder server --dev
+  ```
+
+1. Open a new terminal and run:
+
+  ```console
+  coder templates init
+  ```
+
+1. Select the **Develop code-server in Docker** option when prompted.
+
+1. Navigate into your new folder and create your sample template:
+
+  ```console
+  cd code-server-docker && coder templates create
+  ```
+
+  Follow the prompts that appear in the terminal.
+
+1. Create your workspace:
+
+  ```console
+  coder create --template="docker-code-server" [workspace name]
+  ```
+
+1. Log into Coder's Web UI, and open your workspace. Then,
+   click **code-server** to launch VS Code in a new browser window.
+
+## JetBrains Gateway with SSH
+
+If your image
+[includes a JetBrains IDE](../admin/workspace-management/installing-jetbrains.md)
+and you've [set up SSH access to Coder](./ssh.md), you can use JetBrains Gateway
+to run a local JetBrains IDE connected to your Coder workspace.
+
+> See the [Docker sample template](../examples/templates/docker/main.tf) for an
+> example of how to refer to images in your template.
+
+Please note that:
+
+- Your Coder workspace must be running, and Gateway needs compute resources, so
+  monitor your resource usage on the Coder dashboard and adjust accordingly.
+- If you use a premium JetBrains IDE (e.g., GoLand, IntelliJ IDEA Ultimate), you
+  will still need a license to use it remotely with Coder.
+
+1. [Download and install JetBrains Toolbox](https://www.jetbrains.com/toolbox-app/).
+   Locate JetBrains Gateway in the Toolbox list and click **Install**.
+
+1. Open JetBrains Gateway and click **Connect via SSH** within the **Run the IDE
+   Remotely** section.
+
+1. Click the small **gear icon** to the right of the **Connection** field, then
+   the **+** button on the next screen to create a new configuration.
+
+1. Enter your Coder workspace alias target in **Host** (e.g.,
+   `coder.<yourWorkspaceName>`), `22` in **Port**, `coder` in **User name**, and change
+   **Authentication Type** to **OpenSSH config and authentication agent**. Leave
+   the local port field blank. Click **Test Connection**. If the test is
+   successful, click **Ok** at the bottom to proceed.
+
+1. With your created configuration in the **Connection** chosen in the drop-down
+   field, click **Check Connection and Continue**.
+
+1. Select a JetBrains IDE from the **IDE version** drop-down (make sure that you
+   choose the IDE included in your image), then click the folder icon and select the
+   `/home/coder` directory in your Coder workspace. Click **Download and Start
+   IDE** to proceed.
+
+1. During this installation step, Gateway downloads the IDE and a JetBrains
+   client. This may take a couple of minutes.
+
+1. When your IDE download is complete, JetBrains will prompt you for your
+   license. When done, you'll be able to use your IDE.
diff --git a/docs/templates.md b/docs/templates.md
@@ -23,22 +23,6 @@ vim <template-name>/main.tf
 coder templates <create/update> <template-name>
 ```
 
-## Persistent and ephemeral resources
-
-Coder supports both ephemeral and persistent resources in workspaces. Ephemeral
-resources are destroyed when a workspace is not in use (e.g., when it is
-stopped). Persistent resources remain. See how this works for a sample front-end
-template:
-
-| Resource                     | Type       |
-| :--------------------------- | :--------- |
-| google_compute_disk.home_dir | persistent |
-| kubernetes_pod.dev           | ephemeral  |
-| └─ nodejs (linux, amd64)     |            |
-| api_token.backend            | ephemeral  |
-
-When a workspace is deleted, all resources are destroyed.
-
 ## Parameters
 
 Templates often contain *parameters*. In Coder, there are two types of parameters:
@@ -47,10 +31,9 @@ Templates often contain *parameters*. In Coder, there are two types of parameter
   are often cloud secrets, such as a `ServiceAccount` token, and are annotated
   with `sensitive =  true` in the template code.
 
-- **User parameters** are set when a user creates a workspace. They are unique to
-each workspace, often personalization settings such as "preferred
-region" or "workspace image".
-
+- **User parameters** are set when a user creates a workspace. They are unique
+  to each workspace, often personalization settings such as "preferred region"
+  or "workspace image".
 
 ## Best Practices
 
@@ -70,12 +53,12 @@ provider credentials out of Coder's database (making it a less valuable target f
 and is compatible with agent-based authentication schemes (that handle credential rotation
 and/or ensure the credentials are not written to disk).
 
-Cloud providers for which the Terraform provider supports authenticated environments include
+Cloud providers for which the Terraform provider supports authenticated environments include:
 
- * [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs)
- * [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
- * [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)
- * [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs)
+- [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs)
+- [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
+- [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)
+- [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs)
 
 Additional providers may be supported; check the
 [documentation of the Terraform provider](https://registry.terraform.io/browse/providers) for

diff --git a/docs/workspaces.md b/docs/workspaces.md
@@ -10,40 +10,15 @@ templates](./templates.md):
 
 ```sh
 # create a workspace from the template; specify any variables
-coder create <workspace-name>
+create --template="<templateName>" <workspaceName>
 
 # show the resources behind the workspace and how to connect
 coder show <workspace-name>
 ```
 
-## Connect with SSH
+## IDEs
 
-Once you've added your workspaces to your SSH hosts, you can connect from any
-IDE with remote development support:
-
-```sh
-coder config-ssh
-coder ssh <workspaceName>
-```
-
-## Editors and IDEs
-
-The following desktop IDEs have been tested with Coder, though any IDE with SSH
-support should work!
-
-- VS Code (with [Remote -
-  SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)
-  extension)
-- JetBrains (with
-  [Gateway](https://www.jetbrains.com/help/idea/remote-development-a.html#launch_gateway)
-  installed)
-  - IntelliJ IDEA
-  - CLion
-  - GoLand
-  - PyCharm
-  - Rider
-  - RubyMine
-  - WebStorm
+Coder [supports multiple IDEs](ides.md) for use with your workspaces.
 
 ## Workspace lifecycle
 
@@ -67,8 +42,10 @@ When a workspace is deleted, all of the workspace's resources are deleted.
 
 ## Dotfiles
 
-Users can install configuration from a personal [dotfiles repository](https://dotfiles.github.io) with the `coder dotfiles <repo>`
-command in their workspace. Templates can also prompt users for their dotfiles repo [(example)](../examples/templates/docker-with-dotfiles/README.md#how-it-works).
+Users can install configuration from a personal [dotfiles
+repository](https://dotfiles.github.io) with the `coder dotfiles <repo>` command
+in their workspace. Templates can also prompt users for their dotfiles repo
+[(example)](../examples/templates/docker-with-dotfiles/README.md#how-it-works).
 
 ## Updating workspaces