update docs readme

EdwardAngert · EdwardAngert · commit 0c5212fcae98 · 2024-09-27T20:05:38.000Z
diff --git a/docs/README.md b/docs/README.md
@@ -1,106 +1,131 @@
-# About Coder
+# What is Coder
 
-Coder is an open-source platform for creating and managing developer workspaces
-on your preferred clouds and servers.
+Coder is a self-hosted, open source, cloud development environment that works
+with any cloud, IDE, OS, Git provider, and IDP.
 
-<p align="center">
-  <img src="./images/hero-image.png">
-</p>
+![Screenshots of Coder workspaces and connections](./images/hero-image.png)_Screenshots of Coder workspaces and connections_
 
-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 is built on common development interfaces and infrastructure tools to
+make the process of provisioning and accessing remote workspaces approachable
+for organizations of various sizes and stages of cloud-native maturity.
 
-<blockquote class="warning">
-  <p>
-  If you are a Coder v1 customer, view <a href="https://coder.com/docs/coder">the docs</a> or <a href="https://coder.com/docs/coder/latest/guides/v2-faq">the sunset plans</a>.
-  </p>
-</blockquote>
+> **Using Coder v1?**
+>
+> If you're a Coder v1 customer, view [the v1 documentation](https://coder.com/docs/v1)
+or [the v2 migration guide and FAQ](https://coder.com/docs/v1/guides/v2-faq).
 
-## How it works
+## IDE support
 
-Coder workspaces are represented with Terraform, but no Terraform knowledge is
-required to get started. We have a [database](https://registry.coder.com/templates) of pre-made templates built into the
-product.
+![IDE icons](./images/ide-icons.svg)
 
-<p align="center">
-  <img src="./images/providers-compute.png">
-</p>
+You can use:
 
-Coder workspaces don't stop at compute. You can add storage buckets, secrets, sidecars
-and whatever else Terraform lets you dream up.
+- Any Web IDE, such as
+  - The built-in [VS Code code-server](https://github.com/coder/code-server)
+  - [JetBrains Projector](https://github.com/JetBrains/projector-server)
+  - [Jupyter](https://jupyter.org/)
+  - And others
 
-[Learn more about templates.](./admin/templates/README.md)
+- Your existing remote development environment:
+  - [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/)
+  - [VS Code Remote](https://code.visualstudio.com/docs/remote/ssh-tutorial)
+  - [Emacs](./ides/emacs-tramp)
 
-## IDE Support
-
-You can use any [Web IDE](./admin/templates/extending-templates/web-ides.md) ([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>
+- File sync such as [Mutagen](https://mutagen.io/)
 
 ## Why remote development
 
-Migrating from local developer machines to workspaces hosted by cloud services
-is an [increasingly common solution for
-developers](https://blog.alexellis.io/the-internet-is-my-computer/) and
-[organizations
-alike](https://slack.engineering/development-environments-at-slack). There are
-several benefits, including:
+Remote development offers several benefits for users and administrators, including:
+
+- **Increased speed**
+  - Server-grade cloud hardware speeds up operations in software development, from
+  loading the IDE to compiling and building code, and running large workloads
+  such as those for monolith or microservice applications.
 
-- **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**
+  - Built-in infrastructure tools such as Terraform, nix, Docker, Dev Containers, and others make it easier to onboard developers with consistent environments.
 
-- **Easier environment management:** Tools such as Terraform, nix, Docker,
-  devcontainers, and so on make developer onboarding and the troubleshooting of
-  development environments easier
+- **Increased security**
+  - Centralize source code and other data onto private servers or cloud services instead of local developers' machines.
+  - Provision and manage users with [SSO](https://coder.com/docs/admin/auth) and [Role-based access controlled (RBAC)](https://coder.com/docs/admin/rbac).
 
-- **Increase security:** Centralize source code and other data onto private
-  servers or cloud services instead of local developer machines
+- **Improved compatibility**
+  - Remote workspaces can share infrastructure configurations with other
+  development, staging, and production environments, reducing configuration
+  drift.
 
-- **Improved compatibility:** Remote workspaces share infrastructure
-  configuration with other development, staging, and production environments,
-  reducing configuration drift
+- **Improved accessibility**
+  - Connect to remote workspaces via browser-based IDEs or remote IDE
+  extensions to enable developers regardless of the device they use, whether
+  it's their main device, a lightweight laptop, Chromebook, or iPad.
 
-- **Improved accessibility:** Devices such as lightweight notebooks,
-  Chromebooks, and iPads can connect to remote workspaces via browser-based IDEs
-  or remote IDE extensions
+Read more about why organizations and engineers are moving to remote
+development on [our blog](https://coder.com/blog), the
+[Slack engineering blog](https://slack.engineering/development-environments-at-slack),
+or from [OpenFaaS's Alex Ellis](https://blog.alexellis.io/the-internet-is-my-computer/).
 
 ## Why Coder
 
-The key difference between Coder OSS and other remote IDE platforms is the added
-layer of infrastructure control. This additional layer allows admins to:
+The key difference between Coder 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)
+- Simultaneously support ARM, Windows, Linux, and macOS workspaces.
+- Modify pod/container specs, such as adding disks, managing network policies, or
+  setting/updating environment variables.
+- Use VM or 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
+  hosted by a cloud service.
+
+## How much does it cost?
+
+Coder is free and open source under
+[GNU Affero General Public License v3.0](https://github.com/coder/coder/blob/main/LICENSE).
+All developer productivity features are included in the Open Source version of
+Coder.
+An [Enterprise license is available](https://coder.com/pricing) for enhanced
+support options and custom deployments.
+
+## How does Coder work
+
+Coder workspaces are represented with Terraform, but you don't need to know
+Terraform to get started.
+We have a [database of production-ready templates](https://registry.coder.com/templates)
+for use with AWS EC2, Azure, Google Cloud, Kubernetes, and more.
+
+![Providers and compute environments](./images/providers-compute.png)_Providers and compute environments_
+
+Coder workspaces can be used for more than just compute.
+You can use Terraform to add storage buckets, secrets, sidecars,
+[and more](https://developer.hashicorp.com/terraform/tutorials).
 
-Coder includes [production-ready templates](https://registry.coder.com/templates) for use with AWS EC2,
-Azure, Google Cloud, Kubernetes, and more.
+Visit the [templates documentation](./admin/templates/README.md) to learn more.
 
-## What Coder is _not_
+## 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 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
+- Coder is not a DevOps/CI platform.
+  - Coder workspaces can be configured to 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 an online IDE.
+  - Coder supports common editors, such as VS Code, vim, and JetBrains,
+  all over HTTPS or SSH.
 
-- Coder is not a collaboration platform. You can use git and dedicated IDE
+- Coder is not a collaboration platform.
+  - You can use Git with your favorite Git platform 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.
+- Coder is not a SaaS/fully-managed offering.
+  - Coder is a [self-hosted](https://en.wikipedia.org/wiki/Self-hosting_(web_services))
+  solution.
+  You must host Coder in a private data center or on a cloud service, such as
+  AWS, Azure, or GCP.
 
 ## Up next
 
