docs: slim down readme (#2140)

* docs: move docs table of contents to docs/index.md * docs: move how it works and IDE support to about.md * docs: move readme steps to walkthrough * docs: slim down readme * refactor: walkthrough -> quickstart * docs: minor edits
coder · Jun 8, 2022 · b6899e2 · b6899e2
1 parent 8cfe223
commit b6899e2
Show file tree

Hide file tree

Showing 4 changed files with 101 additions and 95 deletions.
diff --git a/README.md b/README.md
@@ -8,58 +8,30 @@ Discord"](https://img.shields.io/badge/join-us%20on%20Discord-gray.svg?longCache
 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)
 
-## Run Coder *now*
-
-```curl -L https://coder.com/install.sh | sh```
-
-## What Coder does
-Coder creates remote development machines so you can develop your code from anywhere. #coder
-
-> **Note**:
-> Coder is in an alpha state, but any serious bugs are P1 for us so [please report them](https://github.com/coder/coder/issues/new/choose).
+Coder creates remote development machines so your team can develop from anywhere.
 
 <p align="center">
   <img src="./docs/images/hero-image.png">
 </p>
 
-**Code more**
-
-- Build and test faster
-  - Leveraging cloud CPUs, RAM, network speeds, etc.
-- Access your environment from any place on any client (even an iPad)
-- Onboard instantly then stay up to date continuously
-
 **Manage less**
 
 - Ensure your entire team is using the same tools and resources
   - Rollout critical updates to your developers with one command
 - Automatically shut down expensive cloud resources
 - Keep your source code and data behind your firewall
 
-## 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="./docs/images/providers-compute.png">
-</p>
-
-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.](./docs/templates.md)
-
-## IDE Support
+**Code more**
 
-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/).
+- Build and test faster
+  - Leveraging cloud CPUs, RAM, network speeds, etc.
+- Access your environment from any place on any client (even an iPad)
+- Onboard instantly then stay up to date continuously
 
-<p align="center">
-  <img src="./docs/images/ide-icons.svg" height=72>
-</p>
+## Getting Started
 
-## Installing Coder
+> **Note**:
+> Coder is in an alpha state. [Report issues here](https://github.com/coder/coder/issues/new).
 
 There are a few ways to install Coder: [install script](./docs/install.md#installsh) (macOS, Linux), [docker-compose](./docs/install.md#docker-compose), or [manually](./docs/install.md#manual) via the latest release (macOS, Windows, and Linux).
 
@@ -81,66 +53,11 @@ Once installed, you can run a temporary deployment in dev mode (all data is in-m
 coder server --dev
 ```
 
-Use `coder --help` to get a complete list of flags and environment variables.
-
-## Creating your first template and workspace
-
-In a new terminal window, run the following to copy a sample template:
-
-```bash
-coder templates init
-```
-
-Follow the CLI instructions to modify and create the template specific for your
-usage (e.g., a template to **Develop in Linux on Google Cloud**).
-
-Create a workspace using your template:
-
-```bash
-coder create --template="yourTemplate" <workspaceName>
-```
-
-Connect to your workspace via SSH:
-
-```bash
-coder ssh <workspaceName>
-```
-
-## Modifying templates
-
-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
-```
+Use `coder --help` to get a complete list of flags and environment variables. Use our [quickstart guide](./docs/quickstart.md) for a full walkthrough.
 
 ## Documentation
 
-- [About Coder](./docs/about.md#about-coder)
-  - [Why remote development](./docs/about.md#why-remote-development)
-  - [Why Coder](./docs/about.md#why-coder)
-  - [What Coder is not](./docs/about.md#what-coder-is-not)
-  - [Comparison: Coder vs. [product]](./docs/about.md#comparison)
-- [Templates](./docs/templates.md)
-  - [Manage templates](./docs/templates.md#manage-templates)
-  - [Persistent and ephemeral
-    resources](./docs/templates.md#persistent-and-ephemeral-resources)
-  - [Parameters](./docs/templates.md#parameters)
-- [Workspaces](./docs/workspaces.md)
-  - [Create workspaces](./docs/workspaces.md#create-workspaces)
-  - [Connect with SSH](./docs/workspaces.md#connect-with-ssh)
-  - [Editors and IDEs](./docs/workspaces.md#editors-and-ides)
-  - [Workspace lifecycle](./docs/workspaces.md#workspace-lifecycle)
-  - [Updating workspaces](./docs/workspaces.md#updating-workspaces)
-
-## Community
-
-Join the community on [Discord](https://discord.gg/coder) and [Twitter](https://twitter.com/coderhq) #coder!
-
-[Suggest improvements and report problems](https://github.com/coder/coder/issues/new/choose)
+Visit our docs [here](./docs/index.md).
 
 ## Comparison
 
@@ -155,7 +72,13 @@ Please file [an issue](https://github.com/coder/coder/issues/new) if any informa
 
 ---
 
-_As of 5/27/22_
+_Last updated: 5/27/22_
+
+## Community and Support
+
+Join our community on [Discord](https://discord.gg/coder) and [Twitter](https://twitter.com/coderhq)!
+
+[Suggest improvements and report problems](https://github.com/coder/coder/issues/new/choose)
 
 ## Contributing
 

diff --git a/docs/about.md b/docs/about.md
@@ -9,6 +9,29 @@ By building on top of common development interfaces (SSH) and infrastructure too
 > 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/providers-compute.png">
+</p>
+
+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

diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,23 @@
+# Coder Documentation
+
+## 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)
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -0,0 +1,37 @@
+# Quickstart
+
+This guide will walk you through creating your first template and workspace. If you haven't already installed `coder`, do that first [here](./install.md).
+
+## Creating your first template and workspace
+
+In a new terminal window, run the following to copy a sample template:
+
+```bash
+coder templates init
+```
+
+Follow the CLI instructions to modify and create the template specific for your
+usage (e.g., a template to **Develop in Linux on Google Cloud**).
+
+Create a workspace using your template:
+
+```bash
+coder create --template="yourTemplate" <workspaceName>
+```
+
+Connect to your workspace via SSH:
+
+```bash
+coder ssh <workspaceName>
+```
+
+## Modifying templates
+
+If needed, 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
+```