workspaces docs

coder · bpmct · Apr 26, 2022 · Apr 22, 2022 · Apr 22, 2022 · Apr 22, 2022
commit e67dabbe8a1308226d5e70fcaa29016db6cd7c5d
diff --git a/docs/README.md b/docs/README.md
@@ -74,16 +74,15 @@ Some pages are coming soon. Contributions welcome!
   - [Why Coder](about.md#why-coder)
   - [What Coder is not](about.md#what-coder-is-not)
 - [Templates](./templates.md)
-  - [Managing templates](./templates.md#managing-templates)
-  - [Persistant and ephemeral resources](./templates.md#persistant-and-ephemeral-resources)
+  - [Manage templates](./templates.md#manage-templates)
+  - [Persistent and ephemeral resources](./templates.md#persistent-and-ephemeral-resources)
   - [Variables](./templates.md#variables)
 - [Workspaces](./workspaces.md)
-  - [Managing workspaces](./workspaces.md)
+  - [Create workspaces](./workspaces.md#create-workspaces)
+  - [Connect with SSH](./workspaces.md#connect-with-ssh)
   - [Editors and IDEs](./workspaces.md#editors-and-ides)
-- Guides
-  - Using the Coder CLI
-  - Install Coder on a VM with Caddy + LetsEncrypt
-  - Building templates in Coder
+  - [Workspace lifecycle](./workspaces.md#workspace-lifecycle)
+  - [Updating workspaces](./workspaces.md#updating-workspaces)
 
 ## Contributing
 

diff --git a/docs/templates.md b/docs/templates.md
@@ -4,7 +4,7 @@ Coder admins manage *templates* to define the infrastructure behind workspaces.
 
 Templates are shared and updates can be rolled out, or users can manually update their workspaces.
 
-## Managing templates
+## Manage templates
 
 Coder provides production-ready template [examples](../examples/), but they can be modified with Terraform.
 
@@ -21,9 +21,9 @@ coder templates <create/update> <template-name>
 
 If you are commonly editing templates, we recommend source-controlling template code using GitOps/CI pipelines to make changes.
 
-## Persistant and ephemeral resources
+## Persistent and ephemeral resources
 
-Coder supports ephemeral and persistant resources in workspaces. Ephemeral resources are be destroyed when a workspace is not in use (stopped). Persistant resources remain. See how this works for an example "frontend" template:
+Coder supports ephemeral and persistent resources in workspaces. Ephemeral resources are be destroyed when a workspace is not in use (stopped). persistent resources remain. See how this works for an example "frontend" template:
 
 | Resource                     | Type       |
 | :--------------------------- | :--------- |

diff --git a/docs/workspaces.md b/docs/workspaces.md
@@ -1,5 +1,59 @@
 # Workspaces
 
-Coder users create workspaces 
+Workspaces contain the dependencies, IDEs, and configuration information needed for software development.
 
-## Managing workspaces
+## Create workspaces
+
+Each Coder user has their own workspaces, created from a shared [template](./templates.md).
+
+```sh
+# create a workspace from template, specify any variables
+coder workspaces create <workspace-name>
+
+# show the resources behind the workspace, and how to connect
+coder workspaces show <workspace-name>
+```
+
+## Connect with SSH
+
+Once Coder workspaces are added to your SSH hosts, you can connect from any IDE with remote development support.
+
+```sh
+coder config-ssh
+
+ssh coder.<workspace-name>
+```
+
+## Editors and IDEs
+
+The following desktop IDEs have been tested with Coder. 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
+
+## Workspace lifecycle
+
+Workspaces in Coder are started and stopped, often based on activity or when a [template update](./templates.md#manage-templates) is available.
+
+While the exact behavior depends on the template, resources are often destroyed and re-created when a workspace is restarted. For more details, see [persistent and ephemeral resources](./templates.md#persistent-and-ephemeral-resources).
+
+> ⚠️ To avoid data loss, reference your template documentation to see where to store files, install software, etc. Default templates are documented in [../examples](../examples/).
+>
+> You can use `coder workspace show <workspace-name>` to see which resources are persistent vs ephemeral.
+
+When a workspace is deleted, all of the workspace's resources are deleted.
+
+## Updating workspaces
+
+Use the following command to update a workspace to the latest version of a template. The workspace will be stopped and started.
+
+```sh
+coder workspaces update <workspace-name>
+```