coder · bpmct · Apr 26, 2022 · Apr 22, 2022 · Apr 22, 2022 · Apr 22, 2022
diff --git a/docs/README.md b/docs/README.md
@@ -10,9 +10,10 @@ Provision remote development environments with Terraform.
 - Start writing code with a single command
 - Use one of many [examples](./examples) to get started
 
-## Getting Started
+## Installing Coder
 
-Install [the latest release](https://github.com/coder/coder/releases).
+Install [the latest release](https://github.com/coder/coder/releases) on a system with
+at least 2 CPU cores and 2 GB RAM.
 
 To tinker, start with dev-mode (all data is in-memory, and is destroyed on exit):
 
@@ -27,33 +28,35 @@ $ CODER_PG_CONNECTION_URL="postgres://<username>@<host>/<database>?password=<pas
     coder server
 ```
 
-To run as a system service, install with `.deb` or `.rpm`:
+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
 ```
 
+Reference `coder start --help` for a complete list of flags and environment variables.
+
 ### Your First Workspace
 
-In a new terminal, create a new project (eg. Develop in Linux on Google Cloud):
+In a new terminal, create a new template (eg. Develop in Linux on Google Cloud):
 
 ```
 $ coder templates init
 $ coder templates create
 ```
 
-Create a new workspace and SSH in:
+Create a new workspace and connect via SSH:
 
 ```
 $ coder workspaces create my-first-workspace
 $ coder ssh my-first-workspace
 ```
 
-### Working with Projects
+### Modifying Templates
 
-You can edit the Terraform from a sample project:
+You can edit the Terraform from a sample template:
 
 ```sh
 $ coder templates init
@@ -62,6 +65,23 @@ $ vim main.tf
 $ coder templates update gcp-linux
 ```
 
+## Documentation
+
+- [About Coder](./about.md#about-coder)
+  - [Why remote development](about.md#why-remote-development)
+  - [Why Coder](about.md#why-coder)
+  - [What Coder is not](about.md#what-coder-is-not)
+- [Templates](./templates.md)
+  - [Manage templates](./templates.md#manage-templates)
+  - [Persistent and ephemeral resources](./templates.md#persistent-and-ephemeral-resources)
+  - [Variables](./templates.md#variables)
+- [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)
+  - [Workspace lifecycle](./workspaces.md#workspace-lifecycle)
+  - [Updating workspaces](./workspaces.md#updating-workspaces)
+
 ## Contributing
 
 Read the [contributing docs](./CONTRIBUTING.md).

diff --git a/docs/about.md b/docs/about.md
@@ -0,0 +1,52 @@
+# About Coder
+
+Coder is an open source platform for creating and managing developer workspaces on your preferred clouds and servers.
+
+By building on top of common development interfaces (SSH) and infrastructure tools (Terraform), Coder aims to make the process of **provisioning** and **accessing** remote workspaces approachable for organizations of various sizes and stages of cloud-native maturity.
+
+> ⚠️ Coder v2 is in alpha and not ready for production use. You may be interested in [Coder v1](https://coder.com/docs) or [code-server](https://github.com/cdr/code-server).
+
+## Why remote development
+
+Migrating from local developer machines to remote servers is an increasingly common solution for developers[^1] and organizations[^2] alike. Remote development has a number of benefits:
+
+- Speed: Server-grade compute speeds up operations in software development such as IDE loads, compiles, builds, and running large workloads (monolyth or microservice applications). 
+
+- Environment management: Onboarding & troubleshooting development environments is automated using tools such as Terraform, nix, Docker, devcontainers, etc.
+
+- Security: Source code and other data can be centralized on private servers or cloud, instead of local developer machines.
+
+- Compatibility: Remote workspaces share infrastructure configuration with other developer, staging, and production environments, reducing configuration drift.
+
+- Accessibility: Devices such as light notebooks, Chromebooks, and iPads connect to remote workspaces via browser-based IDEs or remote IDE extensions.
+
+## Why Coder?
+
+The added layer of infrastructure control is a key differentiator from Coder v1 and other remote IDE platforms. This gives admins the ability to:
+
+- support ARM, Windows, Linux, and MacOS workspaces
+- modify pod/container spec: add disks, manage network policy, environment variables
+- use VM/dedicated workspaces: develop with Kernel features, container knowledge not required
+- enable persistent workspaces: just like a local machine, but faster and in the cloud
+
+Coder includes [production-ready templates](../examples) for use on Kubernetes, AWS EC2, Google Cloud, Azure, and more.
+
+## What Coder is not
+
+- Coder is an infrastructure as code (IaC) platform. Terraform is the first IaC *provisioner* in Coder. As a result, Coder admins can define any Terraform resources can as Coder workspaces. 
+
+- Coder is not a DevOps/CI platform. Coder workspaces can follow best practices for cloud workloads, but Coder is not responsible for how you define or deploy the software you write.
+
+- Coder is not an online IDE. Instead, Coder has strong support for common editors such as VS Code, vim, and JetBrains, over HTTPS or SSH.
+
+- Coder is not a collaboration platform. You can continue using git and IDE extensions for pull requests, code reviews, and pair programming.
+
+- Coder is not SaaS/fully-managed. Install Coder on your cloud (AWS, GCP, Azure) or datacenter.
+
+---
+
+Next: [Templates](./templates.md)
+
+[^1]: alexellis.io: [The Internet is my computer](https://blog.alexellis.io/the-internet-is-my-computer/)
+
+[^2]: slack.engineering: [Development environments at Slack](https://slack.engineering/development-environments-at-slack)
diff --git a/docs/templates.md b/docs/templates.md
@@ -0,0 +1,47 @@
+# Templates
+
+Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have multiple templates for different workloads, such as "frontend development," "windows development," etc.
+
+Templates are shared and updates can be rolled out, or users can manually update their workspaces.
+
+## Manage templates
+
+Coder provides production-ready template [examples](../examples/), but they can be modified with Terraform.
+
+```sh
+# start from an example
+coder templates init
+
+# optional: modify the template
+vim <template-name>/main.tf
+
+# add the template to Coder deployment
+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.
+
+## Persistent and ephemeral resources
+
+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       |
+| :--------------------------- | :--------- |
+| google_compute_disk.home_dir | persistent |
+| kubernetes_pod.dev           | ephemeral  |
+| └─ nodejs (linux, amd64)     |            |
+| api_token.backend            | ephemeral  |
+
+When a workspace is deleted, all related resources are destroyed.
+
+## Variables
+
+Templates often contain *variables*. In Coder, there are two types of variables.
+
+**Admin variables** are set when a template is being created/updated. These are often cloud secrets, such as a ServiceAccount token. These are annotated with `sensitive =  true` in the template code.
+
+**User variables** are set when a user creates a workspace. They are unique to each workspace, often personalization settings such as preferred region or workspace image.
+
+---
+
+Next: [Workspaces](./workspaces.md)
diff --git a/docs/workspaces.md b/docs/workspaces.md
@@ -0,0 +1,59 @@
+# Workspaces
+
+Workspaces contain the dependencies, IDEs, and configuration information needed for software development.
+
+## 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>
+```