Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: slim down readme #2140

Merged
merged 6 commits into from
Jun 8, 2022
Merged

docs: slim down readme #2140

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0b6a177
docs: move docs table of contents to docs/index.md
jsjoeio Jun 7, 2022
2d942c5
docs: move how it works and IDE support to about.md
jsjoeio Jun 7, 2022
ecc83dd
docs: move readme steps to walkthrough
jsjoeio Jun 7, 2022
0f8f45e
docs: slim down readme
jsjoeio Jun 7, 2022
9238232
refactor: walkthrough -> quickstart
jsjoeio Jun 8, 2022
5c40887
docs: minor edits
jsjoeio Jun 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
113 changes: 18 additions & 95 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keep it short and simple.


<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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Diff is hard to read. I just moved these down a bit.


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>
Comment on lines -58 to -60
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While it does take up some scrolling space, we've received some early feedback that the IDE/cloud icons helped explain what Coder does. Do you think these make the README more confusing?

Copy link
Member

@bpmct bpmct Jun 8, 2022 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm... When we use a product screenshot, we can attempt to include the use of the IDE icons and clouds there

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the second idea!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we've received some early feedback that the IDE/cloud icons helped explain what Coder does

I agree with this, but it also makes me wonder, does our copy not convey this already? It probably should! aka the IDE/Cloud icons should be additive and shouldn't be necessary to explain Coder.

## Getting Started

## Installing Coder
> **Note**:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important, but they don't need to know this until they go to install and use it.

> 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).

Expand All @@ -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. For a full walkthrough, follow [this guide](./docs/walkthrough.md).
jsjoeio marked this conversation as resolved.
Show resolved Hide resolved

## 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).
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I called it index.md because that was what first came to mind. Open to other suggestions.


## Comparison

Expand All @@ -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_
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Felt like this was easier to understand


## Community
jsjoeio marked this conversation as resolved.
Show resolved Hide resolved

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

Expand Down
23 changes: 23 additions & 0 deletions docs/about.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 20 additions & 0 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Coder Documentation

## Table of Contents
jsjoeio marked this conversation as resolved.
Show resolved Hide resolved

- [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)
- [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)
37 changes: 37 additions & 0 deletions docs/walkthrough.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# Walkthrough

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
jsjoeio marked this conversation as resolved.
Show resolved Hide resolved

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
```