coder · ammario · Jun 16, 2022 · Jun 16, 2022 · Jun 16, 2022
diff --git a/docs/CONTRIBUTORS.md b/docs/CONTRIBUTORS.md
diff --git a/docs/CODE_OF_CONDUCT.md → docs/contributing/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md → docs/contributing/CODE_OF_CONDUCT.md
diff --git a/docs/SECURITY.md → docs/contributing/SECURITY.md b/docs/SECURITY.md → docs/contributing/SECURITY.md
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -23,7 +23,14 @@
       "title": "Templates",
       "description": "Learn about templates, which define the infrastructure underlying workspaces.",
       "path": "./templates.md",
-      "icon": "<svg viewBox=\"0 0 16 16\" xmlns=\"http://www.w3.org/2000/svg\"> <path d=\"M15.0017 4.0017H1.0017C0.868289 3.99368 0.734692 4.01405 0.609732 4.06147C0.484772 4.10889 0.371292 4.18228 0.276784 4.27678C0.182276 4.37129 0.108891 4.48477 0.0614728 4.60973C0.0140548 4.73469 -0.00631686 4.86829 0.00170278 5.0017V15.0017C-0.00631686 15.1351 0.0140548 15.2687 0.0614728 15.3937C0.108891 15.5186 0.182276 15.6321 0.276784 15.7266C0.371292 15.8211 0.484772 15.8945 0.609732 15.9419C0.734692 15.9894 0.868289 16.0097 1.0017 16.0017H15.0017C15.1351 16.0097 15.2687 15.9894 15.3937 15.9419C15.5186 15.8945 15.6321 15.8211 15.7266 15.7266C15.8211 15.6321 15.8945 15.5186 15.9419 15.3937C15.9894 15.2687 16.0097 15.1351 16.0017 15.0017V5.0017C16.0097 4.86829 15.9894 4.73469 15.9419 4.60973C15.8945 4.48477 15.8211 4.37129 15.7266 4.27678C15.6321 4.18228 15.5186 4.10889 15.3937 4.06147C15.2687 4.01405 15.1351 3.99368 15.0017 4.0017ZM14.0017 14.0017H2.0017V6.0017H14.0017V14.0017Z\" /> <path d=\"M14 0H2V2H14V0Z\" fill=\"#333333\"/> <path d=\"M5 13L10 8L13 13H5Z\" /> <path d=\"M5 10C5.55228 10 6 9.55228 6 9C6 8.44772 5.55228 8 5 8C4.44772 8 4 8.44772 4 9C4 9.55228 4.44772 10 5 10Z\" /> </svg>"
+      "icon": "<svg viewBox=\"0 0 16 16\" xmlns=\"http://www.w3.org/2000/svg\"> <path d=\"M15.0017 4.0017H1.0017C0.868289 3.99368 0.734692 4.01405 0.609732 4.06147C0.484772 4.10889 0.371292 4.18228 0.276784 4.27678C0.182276 4.37129 0.108891 4.48477 0.0614728 4.60973C0.0140548 4.73469 -0.00631686 4.86829 0.00170278 5.0017V15.0017C-0.00631686 15.1351 0.0140548 15.2687 0.0614728 15.3937C0.108891 15.5186 0.182276 15.6321 0.276784 15.7266C0.371292 15.8211 0.484772 15.8945 0.609732 15.9419C0.734692 15.9894 0.868289 16.0097 1.0017 16.0017H15.0017C15.1351 16.0097 15.2687 15.9894 15.3937 15.9419C15.5186 15.8945 15.6321 15.8211 15.7266 15.7266C15.8211 15.6321 15.8945 15.5186 15.9419 15.3937C15.9894 15.2687 16.0097 15.1351 16.0017 15.0017V5.0017C16.0097 4.86829 15.9894 4.73469 15.9419 4.60973C15.8945 4.48477 15.8211 4.37129 15.7266 4.27678C15.6321 4.18228 15.5186 4.10889 15.3937 4.06147C15.2687 4.01405 15.1351 3.99368 15.0017 4.0017ZM14.0017 14.0017H2.0017V6.0017H14.0017V14.0017Z\" /> <path d=\"M14 0H2V2H14V0Z\" fill=\"#333333\"/> <path d=\"M5 13L10 8L13 13H5Z\" /> <path d=\"M5 10C5.55228 10 6 9.55228 6 9C6 8.44772 5.55228 8 5 8C4.44772 8 4 8.44772 4 9C4 9.55228 4.44772 10 5 10Z\" /> </svg>",
+      "children": [
+            {
+              "title": "Authentication & Secrets",
+              "description": "Learn how to authenticate the provisioner",
+              "path": "./templates/authentication.md"
+            }
+          ]
     },
     {
       "title": "Workspaces",
@@ -40,12 +47,12 @@
         {
           "title": "Code of Conduct",
           "description": "See the code of conduct for contributing to Coder.",
-          "path": "./CODE_OF_CONDUCT.md"
+          "path": "./contributing/CODE_OF_CONDUCT.md"
         },
         {
           "title": "Security",
           "description": "How to report vulnerabilities in Coder",
-          "path": "./SECURITY.md"
+          "path": "./contributing/SECURITY.md"
         }
       ]
     }

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -1,7 +1,5 @@
 # Quickstart
 
-This guide will walk you through creating your first template and workspace.
-
 ## Prerequisites
 
 Please [install Coder](./install.md) before proceeding with the steps outlined in this article.

diff --git a/docs/templates.md b/docs/templates.md
@@ -25,51 +25,24 @@ coder templates <create/update> <template-name>
 
 ## Parameters
 
-Templates often contain *parameters*. In Coder, there are two types of parameters:
+Templates often contain _parameters_. In Coder, there are two types of parameters:
 
 - **Admin parameters** are set when a template is created/updated. These values
   are often cloud secrets, such as a `ServiceAccount` token, and are annotated
-  with `sensitive =  true` in the template code.
-
+  with `sensitive = true` in the template code.
 - **User parameters** are set when a user creates a workspace. They are unique
   to each workspace, often personalization settings such as "preferred region"
   or "workspace image".
 
-## Best Practices
-
-### Template Changes
-
-We recommend source controlling your templates.
-
-### Authenticating with Cloud Providers
-
-Coder's provisioner process needs to authenticate with cloud provider APIs to provision
-workspaces. We strongly advise against including credentials directly in your templates. You
-can either pass credentials to the provisioner as parameters, or execute Coder
-in an environment that is authenticated with the cloud provider.
+## Change Management
 
-We encourage the latter where supported.  This approach 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 (that handle credential rotation
-and/or ensure the credentials are not written to disk).
+We recommend source controlling your templates as you would other code.
 
-Cloud providers for which the Terraform provider supports authenticated environments include:
-
-- [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs)
-- [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
-- [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)
-- [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs)
-
-Additional providers may be supported; check the
-[documentation of the Terraform provider](https://registry.terraform.io/browse/providers) for
-details.
-
-The way these generally work is via the credentials being available to Coder either in some
-well-known location on disk (e.g. `~/.aws/credentials` for AWS on posix systems), or via
-environment variables.  It is usually sufficient to authenticate using the CLI or SDK for the
-cloud provider before running Coder for this to work, but check the Terraform provider
-documentation for details.
+CI is as simple as running `coder templates update` with the appropriate
+credentials.
 
 ---
 
 Next: [Workspaces](./workspaces.md)
+
+Next: [Authentication & Secrets](./authentication.md)
diff --git a/docs/templates/authentication.md b/docs/templates/authentication.md
@@ -0,0 +1,34 @@
+# Authentication & Secrets
+
+<blockquote class="danger">
+  <p>
+  Do not store secrets in templates. Assume every user has cleartext access
+  to every template.
+  </p>
+</blockquote>
+
+Coder's provisioner process needs to authenticate with cloud provider APIs to provision
+workspaces. You can either pass credentials to the provisioner as parameters or execute Coder
+in an environment that is authenticated with the cloud provider.
+
+We encourage the latter where supported. This approach 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 (that handle credential rotation
+and/or ensure the credentials are not written to disk).
+
+Cloud providers for which the Terraform provider supports authenticated environments include
+
+- [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs)
+- [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
+- [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)
+- [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs)
+
+Additional providers may be supported; check the
+[documentation of the Terraform provider](https://registry.terraform.io/browse/providers) for
+details.
+
+The way these generally work is via the credentials being available to Coder either in some
+well-known location on disk (e.g. `~/.aws/credentials` for AWS on posix systems), or via
+environment variables. It is usually sufficient to authenticate using the CLI or SDK for the
+cloud provider before running Coder for this to work, but check the Terraform provider
+documentation for details.