Prepared first draft, except docs/templates/open-in-coder.md

coder · matifali · Oct 16, 2023 · Aug 16, 2023 · Aug 17, 2023 · Aug 17, 2023
commit 6bda97064afbb54288ff76f851dc98653d78d918
diff --git a/docs/templates/agent-metadata.md b/docs/templates/agent-metadata.md
@@ -2,9 +2,9 @@
 
 ![agent-metadata](../images/agent-metadata.png)
 
-With agent metadata, template admins can expose operational metrics
-from their workspaces to their users. It is the dynamic complement of
-[Resource Metadata](./resource-metadata.md).
+You can show live operational metrics to workspace users with agent
+metadata. It is the dynamic complement of [Resource
+Metadata](./resource-metadata.md).
 
 You specify agent metadata in the
 [`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent).
@@ -18,9 +18,9 @@ without messy escape codes, just as if you were working in your
 terminal.
 
 Some of the examples use the [`coder stat`](../cli/stat.md) command.
-This is useful for determining CPU and memory usage inside a
-container, which is more accurate than resource usage about the
-workspace's host.
+This is useful for determining CPU and memory usage of the VM or
+container that the workspace is running in, which is more accurate
+than resource usage about the workspace's host.
 
 Here's a standard set of metadata snippets for Linux agents:
 

diff --git a/docs/templates/authentication.md b/docs/templates/authentication.md
@@ -19,8 +19,8 @@ authenticated with the cloud provider.
 We encourage the latter approach where supported:
 
 - Simplifies the template.
-- Keeps cloud provider credentials out of Coder's database (making it
-a less valuable target for attackers).
+- Keeps cloud provider credentials out of Coder's database, making it
+a less valuable target for attackers.
 - Compatible with agent-based authentication schemes, which handle
 credential rotation or ensure the credentials are not written to disk.
 
@@ -35,8 +35,8 @@ It is usually sufficient to authenticate using the CLI or SDK for the
 cloud provider before running Coder, but check the Terraform
 provider's documentation for details.
 
-Cloud providers for which the Terraform provider supports
-authenticated environments include:
+These cloud platforms have Terraform providers that support
+authenticated environments:
 
 - [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs)
 - [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)

diff --git a/docs/templates/best-practices.md b/docs/templates/best-practices.md
@@ -1,7 +1,7 @@
 # Template best practices
 
-We recommend a few ways to manage workspace resources,
-authentication, and versioning.
+We recommend a few ways to manage workspace resources, authentication,
+and versioning.
 
 <children>
 </children>
diff --git a/docs/templates/creating.md b/docs/templates/creating.md
@@ -12,39 +12,45 @@ templates. End users, like developers, create workspaces from them.
 Templates can also be [managed with git](./change-management.md),
 allowing any developer to propose changes to a template.
 
-> [Template RBAC](../admin/rbac.md) lets you give different users and groups access to templates.
+You can give different users and groups access to templates with
+[role-based access control](../admin/rbac.md).
 
 ## Starter templates
 
-We provide starter templates for common cloud providers (e.g. AWS) and
-orchestrators (e.g. Kubernetes). From there, you can modify them to
-use your own images, VPC, cloud credentials, etc. All Terraform
-resources and properties are supported, so fear not if your favorite
-cloud provider isn't here!
+We provide starter templates for common cloud providers, like AWS, and
+orchestrators, like Kubernetes. From there, you can modify them to use
+your own images, VPC, cloud credentials, and so on. Coder supports all
+Terraform resources and properties, so fear not if your favorite cloud
+provider isn't here!
 
 ![Starter templates](../images/templates/starter-templates.png)
 
-If you'd prefer to use the CLI, use `coder templates init`.
+If you prefer to use Coder on the [command line](../cli.md), use
+`coder templates init`.
 
-> The Terraform code for our starter templates are available on our [GitHub](https://github.com/coder/coder/tree/main/examples/templates).
+> Coder starter templates are also available on our [GitHub
+> repo](https://github.com/coder/coder/tree/main/examples/templates).
 
 ## Editing templates
 
 Our starter templates are meant to be modified work for your use
-cases. You can edit a template's files directly in the Coder
+cases. You can edit any template's files directly in the Coder
 dashboard.
 
 ![Editing a template](../images/templates/choosing-edit-template.gif)
 
-If you'd prefer to use the CLI, use `coder templates pull` and `coder
-templates push`.
+If you'd prefer to use the CLI, use `coder templates pull`, edit the
+template files, then `coder templates push`.
 
 > Even if you are a Terraform expert, we suggest reading our [guided
 > tour](./tour.md).
 
 ## Updating templates
 
-Templates are versioned, keeping all developer workspaces up-to-date. When a new version is published, developers are notified to get the latest infrastructure, software, or security patches. Learn more about [change management](./change-management.md).
+Coder tracks templates versions, keeping all developer workspaces
+up-to-date. When you publish a new version, developers are notified to
+get the latest infrastructure, software, or security patches. Learn
+more about [change management](./change-management.md).
 
 ![Updating a template](../images/templates/update.png)
 

diff --git a/docs/templates/customizing.md b/docs/templates/customizing.md
@@ -1,6 +1,7 @@
 # Customizing templates
 
-You can give developers more information and control over their workspaces:
+You can give developers more information and control over their
+workspaces:
 
 <children>
 </children>
diff --git a/docs/templates/devcontainers.md b/docs/templates/devcontainers.md
@@ -1,8 +1,7 @@
 # Devcontainers (alpha)
 
 [Devcontainers](https://containers.dev) are an open source
-specification for defining development
-environments.
+specification for defining development environments.
 
 [envbuilder](https://github.com/coder/envbuilder) is an open source
 project by Coder that runs devcontainers via Coder templates and your
@@ -13,15 +12,15 @@ template to Coder:
 
 - Drop-in migration from Codespaces (or any existing repositories that
   use devcontainers)
-- Easier to start projects from Coder (new workspace, pick starter
-  devcontainer)
+- Easier to start projects from Coder. Just create a new workspace
+  then pick a starter devcontainer.
 - Developer teams can "bring their own image." No need for platform
   teams to manage complex images, registries, and CI pipelines.
 
 ## How it works
 
-Coder admins add a devcontainer-compatible template to Coder
-(envbuilder ). Then developers enter their repository URL as a
+A Coder admin adds a devcontainer-compatible template to Coder
+(envbuilder). Then developers enter their repository URL as a
 [parameter](./parameters.md) when they create their
 workspace. [envbuilder](https://github.com/coder/envbuilder) clones
 the repo and builds a container from the `devcontainer.json` specified
@@ -42,11 +41,10 @@ Your template can prompt the user for a repo URL with
 
 ## Authentication
 
-You may need to authenticate to your container registry
-(e.g. Artifactory) or git provider (e.g. GitLab) to use
-envbuilder. Refer to the [envbuilder
-documentation](https://github.com/coder/envbuilder/) for more
-information.
+You may need to authenticate to your container registry, such as
+Artifactory, or git provider such as GitLab, to use envbuilder. See
+the [envbuilder documentation](https://github.com/coder/envbuilder/)
+for more information.
 
 ## Caching
 

diff --git a/docs/templates/modules.md b/docs/templates/modules.md
@@ -1,12 +1,12 @@
-# Template inheritance
+# Reusing template code
 
 To reuse code across different Coder templates, such as common scripts
 or resource definitions, we suggest using [Terraform
 Modules](https://developer.hashicorp.com/terraform/language/modules).
 
 You can store these modules externally from your Coder deployment,
 like in a git repository or a Terraform registry. This example shows
-how to reference a module in your template:
+how to reference a module from your template:
 
 ```hcl
 data "coder_workspace" "me" {}
@@ -36,14 +36,14 @@ resource "coder_agent" "dev" {
 If you are importing a module from a private git repository, the Coder
 server or [provisioner](../admin/provisioners.md) needs git
 credentials. Since this token will only be used for cloning your
-repositories with modules, it is best to create a token with limited
-access to repositories and no extra permissions. In GitHub, you can
+repositories with modules, it is best to create a token with access
+limited to the repository and no extra permissions. In GitHub, you can
 generate a [fine-grained
 token](https://docs.github.com/en/rest/overview/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28)
-with read only access to repos.
+with read only access to the necessary repos.
 
 If you are running Coder on a VM, make sure that you have `git`
-installed and the `coder` user has access to the following files
+installed and the `coder` user has access to the following files:
 
 ```sh
 # /home/coder/.gitconfig

diff --git a/docs/templates/open-in-coder.md b/docs/templates/open-in-coder.md
@@ -1,6 +1,7 @@
 # Open in Coder
 
-An "Open in Coder" button can be embedded into your git repos or internal wikis to allow developers to quickly launch a new workspace.
+You can embed an "Open in Coder" button into your git repos or
+internal wikis to let developers quickly launch a new workspace.
 
 <video autoplay playsinline loop>
   <source src="https://github.com/coder/coder/blob/main/docs/images/templates/open-in-coder.mp4?raw=true" type="video/mp4">

diff --git a/docs/templates/parameters.md b/docs/templates/parameters.md
@@ -9,9 +9,9 @@ creating workspaces with
 The user can set parameters in the UI and CLI.
 
 You'll likely want to hardcode certain template properties for
-workspaces, such as security group. You can expose other properties
-with parameters to give developers the flexibility to specify their
-own instance size, repo URL, and so on.
+workspaces, such as security group. But you can let developers specify
+other properties with parameters, like instance size, geographical
+location, repository URL, and so on.
 
 This example lets a developer choose a Docker host for the
 workspace:
@@ -54,8 +54,12 @@ provider "docker" {
 
 ## Types
 
-A Coder parameter can have one of these types: `string`,
-`list(string)`, `bool`, and `number`.
+A Coder parameter can have one of these types:
+
+- `string`
+- `bool`
+- `number`.
+- `list(string)`
 
 To specify a default value for a parameter with the `list(string)`
 type use a JSON array and the Terraform
@@ -79,7 +83,7 @@ data "coder_parameter" "security_groups" {
 
 ## Options
 
-A _string_ parameter can provide a set of options to limit the user's
+A `string` parameter can provide a set of options to limit the user's
 choices:
 
 ```hcl
@@ -111,9 +115,9 @@ data "coder_parameter" "docker_host" {
 
 ## Required and optional parameters
 
-A parameter is considered to be _required_ if it doesn't have the
-`default` property. The user **must** provide a value to this
-parameter before creating a workspace.
+A parameter is _required_ if it doesn't have the `default` property.
+The user **must** provide a value to this parameter before creating a
+workspace:
 
 ```hcl
 data "coder_parameter" "account_name" {
@@ -176,13 +180,12 @@ overuse this opportunity.
 ## Ephemeral parameters
 
 Ephemeral parameters are introduced to users in the form of "build
-options." This functionality can be used to model specific behaviors
-within a Coder workspace, such as reverting to a previous image,
-restoring from a volume snapshot, or building a project without
-utilizing cache.
+options." Use ephemeral parameters to model specific behaviors in a
+Coder workspace, such as reverting to a previous image, restoring from
+a volume snapshot, or building a project without using cache.
 
-As these parameters are ephemeral in nature, subsequent builds will
-proceed in the standard manner.
+Since these parameters are ephemeral in nature, subsequent builds
+proceed in the standard manner:
 
 ```hcl
 data "coder_parameter" "force_rebuild" {
@@ -197,12 +200,12 @@ data "coder_parameter" "force_rebuild" {
 
 ## Validating parameters
 
-Rich parameters support multiple validation modes - min, max,
-monotonic numbers, and regular expressions.
+Coder supports rich parameters with multiple validation modes: min,
+max, monotonic numbers, and regular expressions.
 
 ### Number
 
-You can limit a _number_ parameter to `min` and `max` boundaries.
+You can limit a `number` parameter to `min` and `max` boundaries.
 
 You can also specify its monotonicity as `increasing` or `decreasing`
 to verify the current and new values. Use the `monotonic` aatribute
@@ -224,7 +227,7 @@ data "coder_parameter" "instances" {
 
 ### String
 
-You can validate a _string_ parameter to match a regular expression.
+You can validate a `string` parameter to match a regular expression.
 The `regex` property requires a corresponding `error` property.
 
 ```hcl
@@ -233,7 +236,7 @@ data "coder_parameter" "project_id" {
   description = "Alpha-numeric project ID"
   validation {
     regex = "^[a-z0-9]+$"
-    error = "Unfortunately, it isn't a valid project ID"
+    error = "Unfortunately, this isn't a valid project ID"
   }
 }
 ```

diff --git a/docs/templates/resource-metadata.md b/docs/templates/resource-metadata.md
@@ -94,7 +94,7 @@ resource "coder_metadata" "resource_with_icon" {
 }
 ```
 
-To make easier for you to customize your resource we added some
+To make it easier for you to customize your resource we added some
 built-in icons:
 
 - Folder `/icon/folder.svg`

diff --git a/docs/templates/resource-persistence.md b/docs/templates/resource-persistence.md
@@ -1,7 +1,7 @@
-# Resource Persistence
+# Resource persistence
 
 By default, all Coder resources are persistent, but production
-templates **must** employ the practices laid out in this document to
+templates **must** use the practices laid out in this document to
 prevent accidental deletion.
 
 Coder templates have full control over workspace ephemerality. In a
@@ -13,14 +13,14 @@ The needs of most workspaces fall somewhere in the middle, persisting
 user data like filesystem volumes, but deleting expensive,
 reproducible resources such as compute instances.
 
-## Disabling Persistence
+## Disabling persistence
 
 The Terraform [`coder_workspace` data
 source](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace)
-exposes the `start_count = [0 | 1]` attribute. Other resources can
-refer to this attribute to become ephemeral.
+exposes the `start_count = [0 | 1]` attribute. To make a resource ephemeral, you can assign the `start_count` attribute to resource's [`count`](https://developer.hashicorp.com/terraform/language/meta-arguments/count) meta-argument.
 
-For example:
+In this example, Coder will provision or tear down the
+`docker_container` resource:
 
 ```hcl
 data "coder_workspace" "me" {
@@ -33,7 +33,7 @@ resource "docker_container" "workspace" {
 }
 ```
 
-## ⚠️ Persistence Pitfalls
+## ⚠️ Persistence pitfalls
 
 Take this example resource:
 
@@ -47,10 +47,10 @@ resource "docker_volume" "home_volume" {
 ```
 
 Because we depend on `coder_workspace.me.owner`, if the owner changes
-their username, Terraform would recreate the volume (wiping its data!)
-the next time the workspace restarts.
+their username, Terraform will recreate the volume (wiping its data!)
+the next time that Coder starts the workspace.
 
-To prevent this, use immutable IDs instead:
+To prevent this, use immutable IDs:
 
 - `coder_workspace.me.owner_id`
 - `coder_workspace.me.id`
@@ -68,9 +68,9 @@ resource "docker_volume" "home_volume" {
 
 ## 🛡 Bulletproofing
 
-Even if your persistent resource depends exclusively on static IDs, a
-change to the `name` format or other attributes would cause Terraform
-to rebuild the resource.
+Even if your persistent resource depends exclusively on immutable IDs,
+a change to the `name` format or other attributes would cause
+Terraform to rebuild the resource.
 
 You can prevent Terraform from recreating a resource under any
 circumstance by setting the [`ignore_changes = all` directive in the