coder · ammario · Jun 15, 2022 · Jun 15, 2022 · Jun 15, 2022
diff --git a/docs/README.md b/docs/README.md
@@ -1,27 +1,99 @@
-# Coder Documentation
+# 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** state and is not ready for production use. For
+> production environments, please consider [Coder v1](https://coder.com/docs) or
+> [code-server](https://github.com/cdr/code-server).
+
+## How it works
+
+Coder workspaces are represented with Terraform. But, no Terraform knowledge is
+required to get started. We have a database of pre-made templates built into the
+product.
 
 <p align="center">
-  <img src="images/hero-image.png">
+  <img src="./images/providers-compute.png">
 </p>
 
-## Table of Contents
-
-- [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)
-  - [Comparison: Coder vs. [product]](./about.md#comparison)
-- [Quickstart](./quickstart.md)
-  - [Creating your first template and workspace](./quickstart.md#creating-your-first-template-and-workspace)
-  - [Modifying templates](./quickstart.md#modifying-templates)
-- [Templates](./templates.md)
-  - [Manage templates](./templates.md#manage-templates)
-  - [Persistent and ephemeral
-    resources](./templates.md#persistent-and-ephemeral-resources)
-  - [Parameters](./templates.md#parameters)
-- [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)
+Coder workspaces don't stop at compute. You can add storage buckets, secrets, sidecars
+and whatever else Terraform lets you dream up.
+
+[Learn more about managing infrastructure.](./templates.md)
+
+## IDE Support
+
+You can use any Web IDE ([code-server](https://github.com/coder/code-server), [projector](https://github.com/JetBrains/projector-server), [Jupyter](https://jupyter.org/), etc.), [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/), [VS Code Remote](https://code.visualstudio.com/docs/remote/ssh-tutorial) or even a file sync such as [mutagen](https://mutagen.io/).
+
+<p align="center">
+  <img src="./images/ide-icons.svg" height=72>
+</p>
+
+## Why remote development
+
+Migrating from local developer machines to workspaces hosted by cloud services
+is an increasingly common solution for developers[^1] and organizations[^2]
+alike. There are several benefits, including:
+
+- **Increased speed:** Server-grade compute speeds up operations in software
+  development, such as IDE loading, code compilation and building, and the
+  running of large workloads (such as those for monolith or microservice
+  applications)
+
+- **Easier environment management:** Tools such as Terraform, nix, Docker,
+  devcontainers, and so on make developer onboarding and the troubleshooting of
+  development environments easier
+
+- **Increase security:** Centralize source code and other data onto private
+  servers or cloud services instead of local developer machines
+
+- **Improved compatibility:** Remote workspaces share infrastructure
+  configuration with other development, staging, and production environments,
+  reducing configuration drift
+
+- **Improved accessibility:** Devices such as lightweight notebooks,
+  Chromebooks, and iPads can connect to remote workspaces via browser-based IDEs
+  or remote IDE extensions
+
+## Why Coder
+
+The key difference between Coder v2 and other remote IDE platforms is the added
+layer of infrastructure control. This additional layer allows admins to:
+
+- Support ARM, Windows, Linux, and macOS workspaces
+- Modify pod/container specs (e.g., adding disks, managing network policies,
+  setting/updating environment variables)
+- Use VM/dedicated workspaces, developing with Kernel features (no container
+  knowledge required)
+- Enable persistent workspaces, which are like local machines, but faster and
+  hosted by a cloud service
+
+Coder includes [production-ready templates](../examples/templates) for use with AWS EC2,
+Azure, Google Cloud, Kubernetes, and more.
+
+## What Coder is _not_
+
+- Coder is not an infrastructure as code (IaC) platform. Terraform is the first
+  IaC _provisioner_ in Coder, allowing Coder admins to define Terraform
+  resources as Coder workspaces.
+
+- Coder is not a DevOps/CI platform. Coder workspaces can follow best practices
+  for cloud service-based workloads, but Coder is not responsible for how you
+  define or deploy the software you write.
+
+- Coder is not an online IDE. Instead, Coder supports common editors, such as VS
+  Code, vim, and JetBrains, over HTTPS or SSH.
+
+- Coder is not a collaboration platform. You can use git and dedicated IDE
+  extensions for pull requests, code reviews, and pair programming.
+
+- Coder is not a SaaS/fully-managed offering. You must host
+  Coder on a cloud service (AWS, Azure, GCP) or your private data center.
+
+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/about.md b/docs/about.md
diff --git a/docs/install.md b/docs/install.md
@@ -49,7 +49,6 @@ sudo service coder restart
 
 Or run a **temporary deployment** with dev mode (all data is in-memory and destroyed on exit):
 
-
 ```sh
 coder server --dev
 ```
@@ -61,65 +60,65 @@ Coder](https://github.com/coder/coder/releases) installed.
 
 1. Clone the `coder` repository:
 
-    ```console
-    git clone git@github.com:coder/coder.git
-    ```
+   ```console
+   git clone git@github.com:coder/coder.git
+   ```
 
 1. Navigate into the `coder` folder. Coder requires a non-`localhost` access URL
-    for non-Docker-based examples; if you have a public IP or a domain/reverse
-    proxy, you can provide this value before running `docker-compose up` to
-    start the service:
+   for non-Docker-based examples; if you have a public IP or a domain/reverse
+   proxy, you can provide this value before running `docker-compose up` to
+   start the service:
 
-    ```console
-    cd coder
-    CODER_ACCESS_URL=https://coder.mydomain.com
-    docker-compose up
-    ```
+   ```console
+   cd coder
+   CODER_ACCESS_URL=https://coder.mydomain.com
+   docker-compose up
+   ```
 
-    Otherwise, you can start the service:
+   Otherwise, you can start the service:
 
-    ```console
-    cd coder
-    docker-compose up
-    ```
+   ```console
+   cd coder
+   docker-compose up
+   ```
 
-    Alternatively, if you would like to start a **temporary deployment**:
+   Alternatively, if you would like to start a **temporary deployment**:
 
-    ```console
-    docker run --rm -it \
-    -e CODER_DEV_MODE=true \
-    -v /var/run/docker.sock:/var/run/docker.sock \
-    ghcr.io/coder/coder:v0.5.10
-    ```
+   ```console
+   docker run --rm -it \
+   -e CODER_DEV_MODE=true \
+   -v /var/run/docker.sock:/var/run/docker.sock \
+   ghcr.io/coder/coder:v0.5.10
+   ```
 
 1. Follow the on-screen instructions to create your first template and workspace
 
-## Manual 
+## Manual
 
-We publish self-contained .zip and .tar.gz archives in [GitHub releases](https://github.com/coder/coder/releases). The archives bundle `coder` binary. 
+We publish self-contained .zip and .tar.gz archives in [GitHub releases](https://github.com/coder/coder/releases). The archives bundle `coder` binary.
 
 1. Download the [release archive](https://github.com/coder/coder/releases) 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`
 
-    ```sh
-    # ex. MacOS and Linux
-    mv coder /usr/local/bin
-    ```
+   ```sh
+   # ex. MacOS and Linux
+   mv coder /usr/local/bin
+   ```
 
-    > Windows users: see [this guide](https://answers.microsoft.com/en-us/windows/forum/all/adding-path-variable/97300613-20cb-4d85-8d0e-cc9d3549ba23) for adding folders to `PATH`.
+   > Windows users: see [this guide](https://answers.microsoft.com/en-us/windows/forum/all/adding-path-variable/97300613-20cb-4d85-8d0e-cc9d3549ba23) for adding folders to `PATH`.
 
 1. Start a Coder server
 
-    To run a **temporary deployment**, start with dev mode (all data is in-memory and destroyed on exit):
+   To run a **temporary deployment**, start with dev mode (all data is in-memory and destroyed on exit):
 
-    ```bash
-    coder server --dev
-    ```
+   ```bash
+   coder server --dev
+   ```
 
-    To run a **production deployment** with PostgreSQL:
+   To run a **production deployment** with PostgreSQL:
 
-    ```bash
-    CODER_PG_CONNECTION_URL="postgres://<username>@<host>/<database>?password=<password>" \
-      coder server
-    ```
+   ```bash
+   CODER_PG_CONNECTION_URL="postgres://<username>@<host>/<database>?password=<password>" \
+     coder server
+   ```
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -1,17 +1,11 @@
 {
   "versions": ["0.6.2"],
   "routes": [
-    {
-      "title": "Home",
-      "description": "How to install and run Coder",
-      "path": "./README.md",
-      "icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" version=\"1.1\" viewBox=\"0 0 16 16\" width=\"16px\" xml:space=\"preserve\"><path d=\"M15.45,7L14,5.551V2c0-0.55-0.45-1-1-1h-1c-0.55,0-1,0.45-1,1v0.553L9,0.555C8.727,0.297,8.477,0,8,0S7.273,0.297,7,0.555  L0.55,7C0.238,7.325,0,7.562,0,8c0,0.563,0.432,1,1,1h1v6c0,0.55,0.45,1,1,1h3v-5c0-0.55,0.45-1,1-1h2c0.55,0,1,0.45,1,1v5h3  c0.55,0,1-0.45,1-1V9h1c0.568,0,1-0.437,1-1C16,7.562,15.762,7.325,15.45,7z\"></path></svg>"
-    },
     {
       "title": "About",
       "description": "About Coder",
-      "path": "./about.md",
-      "icon": "<svg width=\"20\" height=\"20\" viewBox=\"0 0 20 20\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"><path d=\"M6 2V11H2V15C2 16.7 3.3 18 5 18H15C16.7 18 18 16.7 18 15V2H6ZM16 15C16 15.6 15.6 16 15 16H8V4H16V15Z\" /><path d=\"M14 7H10V9H14V7Z\" /><path d=\"M14 11H10V13H14V11Z\" /></svg>"
+      "path": "./README.md",
+      "icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" version=\"1.1\" viewBox=\"0 0 16 16\" width=\"16px\" xml:space=\"preserve\"><path d=\"M15.45,7L14,5.551V2c0-0.55-0.45-1-1-1h-1c-0.55,0-1,0.45-1,1v0.553L9,0.555C8.727,0.297,8.477,0,8,0S7.273,0.297,7,0.555  L0.55,7C0.238,7.325,0,7.562,0,8c0,0.563,0.432,1,1,1h1v6c0,0.55,0.45,1,1,1h3v-5c0-0.55,0.45-1,1-1h2c0.55,0,1,0.45,1,1v5h3  c0.55,0,1-0.45,1-1V9h1c0.568,0,1-0.437,1-1C16,7.562,15.762,7.325,15.45,7z\"></path></svg>"
     },
     {
       "title": "Installation",