coder · matifali · Oct 16, 2023 · Aug 16, 2023 · Aug 17, 2023 · Aug 17, 2023
diff --git a/docs/images/autostart.png b/docs/images/autostart.png
diff --git a/docs/images/autostop.png b/docs/images/autostop.png
diff --git a/docs/images/creating-workspace-ui.png b/docs/images/creating-workspace-ui.png
diff --git a/docs/images/schedule.png b/docs/images/schedule.png
diff --git a/docs/images/workspace-update.png b/docs/images/workspace-update.png
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -134,75 +134,71 @@
     },
     {
       "title": "Templates",
-      "description": "Learn about templates, which define the infrastructure underlying workspaces",
+      "description": "Templates define the infrastructure for workspaces",
       "path": "./templates/index.md",
       "icon_path": "./images/icons/picture.svg",
       "children": [
         {
-          "title": "Templates & Terraform",
-          "description": "Learn what makes up a template",
-          "path": "./templates/concepts.md",
-          "children": [
-            {
-              "title": "Parameters",
-              "description": "Use parameters to customize templates",
-              "path": "./templates/parameters.md",
-              "icon_path": "./images/icons/code.svg"
-            },
-            {
-              "title": "Terraform Modules",
-              "description": "Reuse code across Coder templates",
-              "path": "./templates/modules.md"
-            },
-            {
-              "title": "Agent Metadata",
-              "description": "Learn how to expose live agent information to users",
-              "path": "./templates/agent-metadata.md",
-              "icon_path": "./images/icons/table-rows.svg"
-            },
-            {
-              "title": "Resource Metadata",
-              "description": "Learn how to expose resource data to users",
-              "path": "./templates/resource-metadata.md",
-              "icon_path": "./images/icons/table-rows.svg"
-            }
-          ]
+          "title": "Creating, editing, and updating templates",
+          "description": "Working with templates",
+          "path": "./templates/creating.md"
+        },
+        {
+          "title": "Your first template",
+          "description": "A tutorial for creating your first template",
+          "path": "./templates/tutorial.md"
         },
         {
-          "title": "Best Practices",
-          "description": "Best practices for writing/managing templates",
+          "title": "Anatomy of a template",
+          "description": "What makes up a template",
+          "path": "./templates/concepts.md"
+        },
+        {
+          "title": "Setting up templates",
+          "description": "Best practices for writing and managing templates",
           "path": "./templates/best-practices.md",
           "children": [
             {
-              "title": "Provider Authentication",
-              "description": "Learn how to authenticate the provisioner",
+              "title": "Change management",
+              "description": "Versioning templates with git and CI",
+              "path": "./templates/change-management.md",
+              "icon_path": "./images/icons/git.svg"
+            },
+            {
+              "title": "Provider authentication",
+              "description": "Authenticate the provisioner",
               "path": "./templates/authentication.md",
               "icon_path": "./images/icons/key.svg"
             },
             {
-              "title": "Resource Persistence",
-              "description": "Learn how resource persistence works in Coder",
+              "title": "Resource persistence",
+              "description": "How resource persistence works in Coder",
               "path": "./templates/resource-persistence.md",
               "icon_path": "./images/icons/infinity.svg"
             },
             {
-              "title": "Change Management",
-              "description": "Learn how to source-control templates with git and CI",
-              "path": "./templates/change-management.md",
-              "icon_path": "./images/icons/git.svg"
+              "title": "Terraform modules",
+              "description": "Reuse code across Coder templates",
+              "path": "./templates/modules.md"
             }
           ]
         },
-
+        {
+          "title": "Customizing templates",
+          "description": "Give information and options to workspace users",
+          "path": "./templates/customizing.md",
+          "children": [
+          ]
+        },
         {
           "title": "Open in Coder",
-          "description": "Learn how to add an \"Open in Coder\" button to your repos",
+          "description": "Add an \"Open in Coder\" button to your repos",
           "path": "./templates/open-in-coder.md",
           "icon_path": "./images/icons/key.svg"
         },
         {
-          "title": "Docker in Workspaces",
-          "description": "Use docker inside containerized templates",
+          "title": "Docker in workspaces",
+          "description": "Use Docker inside containerized templates",
           "path": "./templates/docker-in-workspaces.md",
           "icon_path": "./images/icons/docker.svg"
         },

diff --git a/docs/templates/concepts.md → docs/templates/anatomy.md b/docs/templates/concepts.md → docs/templates/anatomy.md
@@ -1,15 +1,17 @@
-# Template concepts
+# Anatomy of a template
 
-Coder templates are written in [Terraform](https://terraform.io). All Terraform modules, resources, and properties can be provisioned by Coder. The Coder server essentially runs a `terraform apply` every time a workspace is created/started/stopped.
+Coder templates are written in [Terraform](https://terraform.io)-. All Terraform modules, resources, and properties can be provisioned by Coder. The Coder server essentially runs a `terraform apply` every time a workspace is created/started/stopped.
 
 Haven't written Terraform before? Check out Hashicorp's [Getting Started Guides](https://developer.hashicorp.com/terraform/tutorials).
 
 ## Architecture
 
-This is a simplified diagram of our [Kubernetes example template](https://github.com/coder/coder/blob/main/examples/templates/kubernetes/main.tf). Keep reading for a breakdown of each concept.
+This is a simplified diagram of our [Kubernetes starter template](https://github.com/coder/coder/blob/main/examples/templates/kubernetes/main.tf):
 
 ![Template architecture](https://user-images.githubusercontent.com/22407953/257021139-8c95a731-c131-4c4d-85cc-eed6a52e015c.png)
 
+Keep reading for a breakdown of each concept.
+
 ## Coder Terraform Provider
 
 The [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest) makes it possible for standard Terraform resources (e.g. `kubernetes_deployment`) to connect to Coder. Additionally, the provider lets you to customize the behavior of workspaces using your template.
@@ -26,7 +28,7 @@ terraform {
 
 ### coder_agent
 
-All templates need to create & run a Coder agent in order for developers to connect to their workspaces. The Coder agent is a service that runs inside the compute aspect of your workspace (typically a VM or container). You do not need to have any open ports, but the compute will need `curl` access to the Coder server.
+All templates need to create and run a Coder agent to let developers to connect to their workspaces. The `coder_agent` resource runs inside the compute aspect of your workspace (typically a VM or container). You do not need to have any open ports, but the compute will need `curl` access to the Coder server.
 
 This snippet creates the agent, runs it inside the container via the `entrypoint`, and authenticates to Coder via the agent's token.
 
@@ -49,7 +51,7 @@ Agents can also run startup scripts, set environment variables, and provide [met
 
 This data source provides details about the state of a workspace, such as its name, owner, and whether the workspace is being started or stopped.
 
-The following snippet will create a container when the workspace is being started, and delete the container when it is stopped using Terraform's [count](https://developer.hashicorp.com/terraform/language/meta-arguments/count) meta-argument.
+The following snippet creates a container when the workspace is being started, and deletes the container when it is stopped. It does this with Terraform's [count](https://developer.hashicorp.com/terraform/language/meta-arguments/count) meta-argument.
 
 ```hcl
 data "coder_workspace" "me" {}
@@ -135,6 +137,8 @@ data "coder_parameter" "repo" {
 
 Variables for templates are supported and can be managed in template settings.
 
+Use Terraform variables to keep secrets outside of the template. Variables are also useful for adjusting a template without having to commit a new version.
+
 ![Template variables](https://user-images.githubusercontent.com/22407953/257079273-af4720c4-1aee-4451-8fd9-82a8c579f289.png)
 
 > Per-workspace settings can be defined via [Parameters](./parameters.md).

diff --git a/docs/templates/creating.md b/docs/templates/creating.md
@@ -0,0 +1,41 @@
+#  Creating, editing, and updating templates
+
+You create and edit Coder templates as [Terraform](./concepts.md) configuration files (`.tf`).
+
+## Who creates templates?
+
+The [Template Admin](../admin/users.md) role (and above) can create templates. End users (developers) create workspaces from them.
+
+Templates can also be [managed witg 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.
+
+## 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!
+
+![Starter templates](https://user-images.githubusercontent.com/22407953/256705348-e6fb2963-27f5-414f-9f5c-345cd3b7ee28.png)
+
+If you'd prefer to use the CLI, use `coder templates init`.
+
+> The Terraform code for our starter templates are avalible 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.
+
+![Editing a template](https://user-images.githubusercontent.com/22407953/256706060-71fb48f4-9a1b-42ad-9380-0ecc02db3218.gif)
+
+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).
+
+## 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.
+
+![Template update screen](https://user-images.githubusercontent.com/22407953/256712740-96121f81-a3c8-4be0-90dc-c1c4cabed634.png)
+
+## Next step
+
+- [Your first templates](./tutorial.md)
diff --git a/docs/templates/customizing.md b/docs/templates/customizing.md
@@ -0,0 +1,7 @@
+# Customizing templates
+
+You can give developers more information and control over their workspaces:
+
+* [Agent metadata](./agent-metadata.md): Show metrics about the running workspace.
+* [Resource metadata](./resource-metadata.md): Show information about a workspace's resources.
+* [Parameters](./parameters.md): Let the user customize their workspace.
diff --git a/docs/templates/index.md b/docs/templates/index.md
@@ -1,52 +1,7 @@
 # Templates
 
-Templates define the underlying infrastructure that workspaces run on. All Coder workspaces are created from a
-template.
+Templates define the underlying infrastructure that workspaces run on.
+All Coder [workspaces](./workspaces.md) are created from a template.
 
-## Who creates templates?
-
-The [Template Admin](../admin/users.md) role (and above) can create templates. End users (developers) create workspaces from them. However, templates can also be [managed via 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.
-
-## 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!
-
-![Starter templates](https://user-images.githubusercontent.com/22407953/256705348-e6fb2963-27f5-414f-9f5c-345cd3b7ee28.png)
-
-If you'd prefer to use the CLI, use `coder templates init`.
-
-> The Terraform code for our starter templates are avalible on our [GitHub](https://github.com/coder/coder/tree/main/examples/templates).
-
-## Editing templates
-
-Our starter templates are meant to me modified work for your use cases! You can edit the Terraform code for a template directly in the UI.
-
-![Editing a template](https://user-images.githubusercontent.com/22407953/256706060-71fb48f4-9a1b-42ad-9380-0ecc02db3218.gif)
-
-
-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).
-
-## Template updates
-
-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.
-
-![Template update screen](https://user-images.githubusercontent.com/22407953/256712740-96121f81-a3c8-4be0-90dc-c1c4cabed634.png)
-
-## Template parameters
-
-You'll likely want to hardcode certain properties for workspaces (e.g. "security group, VPC"). Others can be exposed via parameters to give developers flexibility (e.g. instance size, GitHub repo URL).
-
-Paramaters let users customize their individual workspaces:
-
-![Parameters in templates](https://user-images.githubusercontent.com/22407953/256707889-18baf2be-2dae-4eb2-ae89-71e5b00248f8.png)
-
-> Paramaters are defined via the template's Terraform code. [Learn more](./parameters.md)
-
-## Next steps
-
-- [Template structure](./structure.md)
-- [Template structure](./structure.md)
+<children>
+</children>
diff --git a/docs/templates/parameters.md b/docs/templates/parameters.md
@@ -2,6 +2,13 @@
 
 Templates can contain _parameters_, which allow prompting the user for additional information when creating workspaces in both the UI and CLI.
 
+You'll likely want to hardcode certain template properties for workspaces (e.g. "security group, VPC"). You can expose other properties via parameters to give developers flexibility (e.g. instance size, GitHub repo URL).
+
+![Parameters in templates](https://user-images.githubusercontent.com/22407953/256707889-18baf2be-2dae-4eb2-ae89-71e5b00248f8.png)
+
+> Paramaters are defined via the template's Terraform code. [Learn more](./parameters.md)
+
+
 ![Parameters in Create Workspace screen](../images/parameters.png)
 
 ```hcl

diff --git a/docs/templates/tutorial.md b/docs/templates/tutorial.md
@@ -0,0 +1,14 @@
+# Your first template
+
+## Install Docker
+
+## Install Coder
+
+## Choose a starter template
+
+## Creating a template for Kubernetes
+
+## Next steps
+
+- [Anatomy of a template](./anatomy.md)
+- [Setting up templates](./best-practices.md)