coder · bpmct · Apr 26, 2022 · Apr 22, 2022 · Apr 22, 2022 · Apr 22, 2022
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -1,48 +1,53 @@
+
 # Contributing
 
 ## Requirements
 
-`coder` requires Go 1.18+, Node 14+, and GNU Make.
+Coder requires Go 1.18+, Node 14+, and GNU Make.
 
-### Development Workflow
+### Development workflow
 
-The following `make` commands and scripts used in development:
+Use the following `make` commands and scripts in development:
 
 - `make bin` builds binaries
 - `make install` installs binaries to `$GOPATH/bin`
 - `make test`
-- `make release` dry-runs a new release
-- `./develop.sh` hot-reloads for frontend development
+- `make release` dry runs a new release
+- `./develop.sh` hot reloads for front-end development
 
 ## Styling
 
-### Go Style
+### Use Go style
 
-Contributions must adhere to [Effective Go](https://go.dev/doc/effective_go). Linting rules should
-be preferred over documenting styles (run ours with `make lint`); humans are error prone!
+Contributions must adhere to the guidelines outlined in [Effective
+Go](https://go.dev/doc/effective_go). We prefer linting rules over documenting
+styles (run ours with `make lint`); humans are error-prone!
 
-Read [Go's Code Review Comments Wiki](https://github.com/golang/go/wiki/CodeReviewComments) to find
+Read [Go's Code Review Comments
+Wiki](https://github.com/golang/go/wiki/CodeReviewComments) for information on
 common comments made during reviews of Go code.
 
-#### No Unused Packages
-
-Coders write packages that are used during implementation. It's difficult to validate whether an
-abstraction is valid until it's checked against an implementation. This results in a larger
-changeset but provides reviewers with an educated perspective on the contribution.
+### Avoid unused packages
 
-## Review
+Coder writes packages that are used during implementation. It isn't easy to
+validate whether an abstraction is valid until it's checked against an
+implementation. This results in a larger changeset, but it provides reviewers
+with a holistic perspective regarding the contribution.
 
-> Taken from [Go's review philosophy](https://go.dev/doc/contribute#reviews).
+## Reviews
 
-Coders value thorough reviews. Think of each review comment like a ticket: you are expected to
-somehow "close" it by acting on it, either by implementing the suggestion or convincing the reviewer
-otherwise.
+> The following information has been borrowed from [Go's review
+> philosophy](https://go.dev/doc/contribute#reviews).
 
-After you update the change, go through the review comments and make sure to reply to every one. You
-can click the "Done" button to reply indicating that you've implemented the reviewer's suggestion;
-otherwise, click on "Reply" and explain why you have not, or what you have done instead.
+Coder values thorough reviews. For each review comment that you receive, please
+"close" it by implementing the suggestion or providing an explanation on why the
+suggestion isn't the best option. Be sure to do this for each comment; you can
+click **Done** to indicate that you've implemented the suggestion, or you can
+add a comment explaining why you aren't implementing the suggestion (or what you
+chose to implement instead).
 
-It is perfectly normal for changes to go through several round of reviews, with one or more
-reviewers making new comments every time and then waiting for an updated change before reviewing
-again. All contributors, including experienced maintainers, are subject to the same review cycle;
-this process is not meant to be applied selectively or discourage anyone from contribution.
+It is perfectly normal for changes to go through several rounds of reviews, with
+one or more reviewers making new comments every time, then waiting for an
+updated change before reviewing again. All contributors, including those from
+maintainers, are subject to the same review cycle; this process is not meant to
+be applied selectively or to discourage anyone from contributing.
diff --git a/docs/README.md b/docs/README.md
@@ -1,68 +1,97 @@
 # Coder
 
-[!["GitHub Discussions"](https://img.shields.io/badge/%20GitHub-%20Discussions-gray.svg?longCache=true&logo=github&colorB=purple)](https://github.com/coder/coder/discussions) [!["Join us on Slack"](https://img.shields.io/badge/join-us%20on%20slack-gray.svg?longCache=true&logo=slack&colorB=brightgreen)](https://coder.com/community) [![Twitter Follow](https://img.shields.io/twitter/follow/CoderHQ?label=%40CoderHQ&style=social)](https://twitter.com/coderhq) [![codecov](https://codecov.io/gh/coder/coder/branch/main/graph/badge.svg?token=TNLW3OAP6G)](https://codecov.io/gh/coder/coder)
+[!["GitHub
+Discussions"](https://img.shields.io/badge/%20GitHub-%20Discussions-gray.svg?longCache=true&logo=github&colorB=purple)](https://github.com/coder/coder/discussions)
+[!["Join us on
+Slack"](https://img.shields.io/badge/join-us%20on%20slack-gray.svg?longCache=true&logo=slack&colorB=brightgreen)](https://coder.com/community)
+[![Twitter
+Follow](https://img.shields.io/twitter/follow/CoderHQ?label=%40CoderHQ&style=social)](https://twitter.com/coderhq)
+[![codecov](https://codecov.io/gh/coder/coder/branch/main/graph/badge.svg?token=TNLW3OAP6G)](https://codecov.io/gh/coder/coder)
 
 Provision remote development environments with Terraform.
 
 ## Highlights
 
-- Automate development environments for Linux, Windows, and MacOS in your cloud
+- Automate development environments for Linux, Windows, and macOS
 - Start writing code with a single command
-- Use one of many [examples](./examples) to get started
+- Get started quickly using one of the [examples](./examples) provided
 
-## 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 1 CPU core and 2 GB RAM.
 
-To tinker, start with dev-mode (all data is in-memory, and is destroyed on exit):
+To test, start with dev mode (all data is in-memory and is destroyed on exit):
 
 ```bash
-$ coder server --dev
+coder server --dev
 ```
 
 To run a production deployment with PostgreSQL:
 
 ```bash
-$ CODER_PG_CONNECTION_URL="postgres://<username>@<host>/<database>?password=<password>" \
+CODER_PG_CONNECTION_URL="postgres://<username>@<host>/<database>?password=<password>" \
     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
+sudo vim /etc/coder.d/coder.env
+sudo service coder restart
 ```
 
-### Your First Workspace
+Use `coder start --help` to get a complete list of flags and environment
+variables.
 
-In a new terminal, create a new project (eg. Develop in Linux on Google Cloud):
+### Your first workspace
 
-```
-$ coder templates init
-$ coder templates create
+In a new terminal, create a template (e.g., a template to **Develop in Linux on
+Google Cloud**):
+
+```bash
+coder templates init
+coder templates create
 ```
 
-Create a new workspace and SSH in:
+Create a workspace and connect to it via SSH:
 
-```
-$ coder workspaces create my-first-workspace
-$ coder ssh my-first-workspace
+```bash
+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 template using a sample template:
 
 ```sh
-$ coder templates init
-$ cd gcp-linux/
-$ vim main.tf
-$ coder templates update gcp-linux
+coder templates init
+cd gcp-linux/
+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/SECURITY.md b/docs/SECURITY.md
@@ -1,4 +1,4 @@
 # Security Policy
 
-Keeping your code secure is core to what we do. If you find a vulnerability,
-please send an email to security@coder.com, and our team will respond to you.
+Keeping your code secure is central to what we do. If you find a vulnerability,
+please send an email to security@coder.com.
diff --git a/docs/about.md b/docs/about.md
@@ -0,0 +1,79 @@
+# 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).
+
+## 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) 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/templates.md b/docs/templates.md
@@ -0,0 +1,58 @@
+# Templates
+
+Templates define the infrastructure underlying workspaces. Each Coder deployment
+can have multiple templates for different workloads, such as ones for front-end
+development, Windows development, and so on.
+
+Coder manage templates, including sharing them and rolling out updates
+to everybody. Users can also manually update their workspaces.
+
+## Manage templates
+
+Coder provides production-ready [sample template](../examples/), but you can
+modify the templates 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>
+```
+
+> We recommend source controlling your templates.
+
+## 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:
+
+- **Admin parameters** are set when a template is created/updated. These values
+  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".
+
+---
+
+Next: [Workspaces](./workspaces.md)