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 start
 ```
 
-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
+
+Some pages are coming soon. Contributions welcome!
+
+- [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)
+- Concepts
+  - Templates
+  - Workspaces
+  - Users and Organizations
+- Guides
+  - Using the Coder CLI
+  - Install Coder on a VM with Caddy + LetsEncrypt
+  - Building templates in Coder
+
 ## Contributing
 
 Read the [contributing docs](./CONTRIBUTING.md).

diff --git a/docs/about.md b/docs/about.md
@@ -0,0 +1,48 @@
+# 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 inferfaces (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 apps (monolyths or many microservices). 
+
+- 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.
+
+- Compatability: 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 persistant 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.
+
+[^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/concepts.md b/docs/concepts.md
@@ -0,0 +1,8 @@
+# Coder Concepts
+
+
+## Templates
+
+Coder admins have the ability to create, update, and delete *templates*. Templates are the blueprint for developer workspaces. 
+
+## Workspaces