Edited and added screenshots

coder · matifali · Oct 16, 2023 · Aug 16, 2023 · Aug 17, 2023 · Aug 17, 2023
commit 9f16953fc89c1650554a3829e36431154f6e543b
diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md
@@ -1,4 +1,4 @@
-# Provisioners
+# External provisioners
 
 By default, the Coder server runs [built-in provisioner daemons](../cli/server.md#provisioner-daemons), which execute `terraform` during workspace and template builds. However, there are sometimes benefits to running external provisioner daemons:
 

diff --git a/docs/images/templates/choosing-edit-template.gif b/docs/images/templates/choosing-edit-template.gif
diff --git a/docs/images/templates/starter-templates-button.png b/docs/images/templates/starter-templates-button.png
diff --git a/docs/images/templates/starter-templates.png b/docs/images/templates/starter-templates.png
diff --git a/docs/images/templates/template-anatomy.png b/docs/images/templates/template-anatomy.png
diff --git a/docs/images/templates/template-architecture.png b/docs/images/templates/template-architecture.png
diff --git a/docs/images/templates/template-tour.png b/docs/images/templates/template-tour.png
diff --git a/docs/images/templates/update.png b/docs/images/templates/update.png
diff --git a/docs/images/templates/update.png:Zone.Identifier b/docs/images/templates/update.png:Zone.Identifier
@@ -0,0 +1,3 @@
+[ZoneTransfer]
+ZoneId=3
+HostUrl=https://user-images.githubusercontent.com/22407953/256712740-96121f81-a3c8-4be0-90dc-c1c4cabed634.png
diff --git a/docs/images/templates/upload.png b/docs/images/templates/upload.png
diff --git a/docs/templates/agent-metadata.md b/docs/templates/agent-metadata.md
@@ -2,10 +2,12 @@
 
 ![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).
+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 specify agent metadata in the [`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent).
+You specify agent metadata in the
+[`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent).
 
 ## Examples
 
@@ -16,8 +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
-instead of the workspace's host, which can be tricky otherwise.
+This is useful for determining CPU and memory usage inside a
+container, which is more accurate than resource usage about the
+workspace's host.
 
 Here's a standard set of metadata snippets for Linux agents:
 
@@ -122,9 +125,9 @@ usr sys idl wai stl| read  writ| recv  send|  in   out | int   csw
 
 ## Managing the database load
 
-Agent metadata can generate a significant write load and overwhelm your
-database if you're not careful. The approximate writes per second can be
-calculated using the formula:
+Agent metadata can generate a significant write load and overwhelm
+your Coder database if you're not careful. The approximate writes per
+second can be calculated using the formula:
 
 ```text
 (metadata_count * num_running_agents * 2) / metadata_avg_interval
@@ -136,7 +139,7 @@ For example, let's say you have
 - each with 6 metadata snippets
 - with an average interval of 4 seconds
 
-You can expect `(10 * 6 * 2) / 4` or 30 writes per second.
+You can expect `(10 * 6 * 2) / 4`, or 30 writes per second.
 
 One of the writes is to the `UNLOGGED` `workspace_agent_metadata`
 table and the other to the `NOTIFY` query that enables live stats

diff --git a/docs/templates/authentication.md b/docs/templates/authentication.md
@@ -7,19 +7,22 @@
   </p>
 </blockquote>
 
-The Coder server's [provisioner](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/provisioner)
-process needs to authenticate with cloud provider APIs to provision
+The Coder server's
+[provisioner](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/provisioner)
+process needs to authenticate with other provider APIs to provision
 workspaces. There are two approaches to do this:
 
 - Pass credentials to the provisioner as parameters.
 - Preferred: Execute the Coder server in an environment that is
 authenticated with the cloud provider.
 
-We encourage the latter approach where supported. This simplifies the
-template, keeps cloud provider credentials out of Coder's database
-(making it a less valuable target for attackers), and is compatible
-with agent-based authentication schemes, which handle credential
-rotation or ensure the credentials are not written to disk.
+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).
+- Compatible with agent-based authentication schemes, which handle
+credential rotation or ensure the credentials are not written to disk.
 
 Generally, you can set up an environment to provide credentials to
 Coder in these ways:

diff --git a/docs/templates/best-practices.md b/docs/templates/best-practices.md
@@ -1,6 +1,6 @@
 # Template best practices
 
-We recommend a few ways to manage persistence of resources,
+We recommend a few ways to manage workspace resources,
 authentication, and versioning.
 
 <children>

diff --git a/docs/templates/change-management.md b/docs/templates/change-management.md
@@ -27,9 +27,10 @@ coder templates push --yes $CODER_TEMPLATE_NAME \
     --name=$CODER_TEMPLATE_VERSION # Version name is optional
 ```
 
+To cap token lifetime on creation, [configure Coder server to set a
+shorter max token lifetime](../cli/server.md#--max-token-lifetime)
+
 > Looking for an example? See how we push our development image and
 > template [via GitHub
 > actions](https://github.com/coder/coder/blob/main/.github/workflows/dogfood.yaml).
 
-> To cap token lifetime on creation, [configure Coder server to set a
-> shorter max token lifetime](../cli/server.md#--max-token-lifetime)
diff --git a/docs/templates/creating.md b/docs/templates/creating.md
@@ -6,37 +6,47 @@ configuration files for other services.
 
 ## Who creates templates?
 
-The [Template Admin](../admin/users.md) role (and above) can create templates. End users (developers) create workspaces from them.
+The [Template Admin](../admin/users.md) role (and above) can create
+templates. End users, like developers, create workspaces from them.
 
-Templates can also be [managed witg git](./change-management.md), allowing any developer to propose changes to a template.
+Templates can also be [managed with git](./change-management.md),
+allowing any developer to propose changes to a template.
 
-> [Template RBAC](../admin/rbac.md) allows you to give different users & groups access to templates.
+> [Template RBAC](../admin/rbac.md) lets you give different users and groups access to templates.
 
 ## Starter templates
 
-We provide starter templates for common cloud providers (e.g. AWS) and orchestrators (e.g. Kubernetes). From there, you can modify them with [Terraform](https://terraform.io) to use your own images, VPC, cloud credentials, etc. All Terraform resources and properties are supported, so fear not if your favorite cloud isn't here!
+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!
 
-![Starter templates](https://user-images.githubusercontent.com/22407953/256705348-e6fb2963-27f5-414f-9f5c-345cd3b7ee28.png)
+![Starter templates](../images/templates/starter-templates.png)
 
 If you'd prefer to use the CLI, use `coder templates init`.
 
-> The Terraform code for our starter templates are availible on our [GitHub](https://github.com/coder/coder/tree/main/examples/templates).
+> The Terraform code for our starter templates are available on our [GitHub](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 the Terraform code for a template directly in the UI.
+Our starter templates are meant to be modified work for your use
+cases. You can edit a template's files directly in the Coder
+dashboard.
 
-![Editing a template](https://user-images.githubusercontent.com/22407953/256706060-71fb48f4-9a1b-42ad-9380-0ecc02db3218.gif)
+![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` and `coder
+templates push`.
 
-> Even if you are a Terraform expert, we suggest reading our full guide on [writing Coder templates](./managing.md).
+> 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.
+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).
 
-![Template update screen](https://user-images.githubusercontent.com/22407953/256712740-96121f81-a3c8-4be0-90dc-c1c4cabed634.png)
+![Updating a template](../images/templates/update.png)
 
 ## Next step
 

diff --git a/docs/templates/index.md b/docs/templates/index.md
@@ -1,7 +1,8 @@
 # Templates
 
-Templates define the underlying infrastructure that workspaces run on.
-All Coder [workspaces](./workspaces.md) are created from templates.
+Templates define the underlying infrastructure that Coder
+[workspaces](../workspaces.md) run on. All workspaces are created from
+templates.
 
 <children>
 </children>
diff --git a/docs/templates/modules.md b/docs/templates/modules.md
@@ -1,13 +1,12 @@
 # Template inheritance
 
-In instances where you want to reuse code across different Coder
-templates, such as common scripts or resource definitions, we suggest
-using [Terraform
+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).
 
-These modules can be stored externally from Coder, like in a Git
-repository or a Terraform registry. This example shows how to
-reference a module in your template:
+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:
 
 ```hcl
 data "coder_workspace" "me" {}
@@ -43,8 +42,8 @@ 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.
 
-If you are running Coder on a VM, make sure you have `git` installed
-and the `coder` user has access to the following files
+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
 
 ```sh
 # /home/coder/.gitconfig

diff --git a/docs/templates/open-in-coder.md b/docs/templates/open-in-coder.md
@@ -98,10 +98,3 @@ To support any infrastructure and software stack, Coder provides a generic appro
 
    ![Pre-filled parameters](../images/templates/pre-filled-parameters.png)
 
-## Example: Kubernetes
-
-For a full example of the Open in Coder flow in Kubernetes, check out [this example template](https://github.com/bpmct/coder-templates/tree/main/kubernetes-open-in-coder).
-
-## Devcontainer support
-
-Devcontainer support is on the roadmap. [Follow along here](https://github.com/coder/coder/issues/5559)
diff --git a/docs/templates/parameters.md b/docs/templates/parameters.md
@@ -1,17 +1,19 @@
 # Parameters
 
-A template can prompt the user for additional information when creating workspaces with  [_parameters_](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter).
+A template can prompt the user for additional information when
+creating workspaces with
+[_parameters_](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter).
 
 ![Parameters in Create Workspace screen](../images/parameters.png)
 
 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, VPC. 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. You can expose other properties
+with parameters to give developers the flexibility to specify their
+own instance size, repo URL, and so on.
 
-This example lets a developer choose the Docker host for the
+This example lets a developer choose a Docker host for the
 workspace:
 
 ```hcl
@@ -42,7 +44,7 @@ data "coder_parameter" "docker_host" {
 }
 ```
 
-From there, a template can refer to parameters at build time:
+From there, a template can refer to a parameter's value:
 
 ```hcl
 provider "docker" {
@@ -77,7 +79,8 @@ data "coder_parameter" "security_groups" {
 
 ## Options
 
-A _string_ parameter can provide a set of options to limit the user's choices:
+A _string_ parameter can provide a set of options to limit the user's
+choices:
 
 ```hcl
 data "coder_parameter" "docker_host" {

diff --git a/docs/templates/resource-metadata.md b/docs/templates/resource-metadata.md
@@ -4,7 +4,8 @@ Expose key workspace information to your users with
 [`coder_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata)
 resources in your template code.
 
-You can use `coder_metadata` to show Terraform resource attributes like these:
+You can use `coder_metadata` to show Terraform resource attributes
+like these:
 
 - Compute resources
 - IP addresses
@@ -17,7 +18,8 @@ You can use `coder_metadata` to show Terraform resource attributes like these:
 Coder automatically generates the <code>type</code> metadata.
 </blockquote>
 
-You can also present automatically updating, dynamic values with [agent metadata](./agent-metadata.md).
+You can also present automatically updating, dynamic values with
+[agent metadata](./agent-metadata.md).
 
 ## Example
 

diff --git a/docs/templates/resource-persistence.md b/docs/templates/resource-persistence.md
@@ -9,9 +9,9 @@ completely ephemeral workspace, there are zero resources in the Off
 state. In a completely persistent workspace, there is no difference
 between the Off and On states.
 
-Most workspaces fall somewhere in the middle, persisting user data
-such as filesystem volumes, but deleting expensive, reproducible
-resources such as compute instances.
+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
 
@@ -50,8 +50,7 @@ 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.
 
-Therefore, persistent resource names must only depend on immutable IDs
-such as:
+To prevent this, use immutable IDs instead:
 
 - `coder_workspace.me.owner_id`
 - `coder_workspace.me.id`
@@ -69,11 +68,11 @@ resource "docker_volume" "home_volume" {
 
 ## 🛡 Bulletproofing
 
-Even if our persistent resource depends exclusively on static IDs, a
+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.
 
-You can prevent Terraform from recreating the resource under any
+You can prevent Terraform from recreating a resource under any
 circumstance by setting the [`ignore_changes = all` directive in the
 `lifecycle`
 block](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes).