add detail to site-wide template policy doc (coder#426)

bpmct · Katie Horne · web-flow · commit 60da9345d6dd · 2021-06-22T21:08:58.000-04:00
* mention fields

* document custom workspaces and conflict behavior

* change formatting

now matches "dev urls - access control" section

* Edit text

Co-authored-by: Katie Horne &lt;katie@coder.com&gt;
diff --git a/admin/templates.md b/admin/templates.md
@@ -1,8 +1,6 @@
 ---
 title: Templates
-description:
-  Learn how to create an embeddable "Open In Coder" button for your Workspaces
-  As Code Template
+description: Learn how to manage your Workspaces as Code Templates.
 ---
 
 The **Templates** tab features options that control the behavior of workspace
@@ -14,56 +12,70 @@ located in Git repositories.
 
 ![Enable workspace templates](../assets/enable-ws-templates.png)
 
-## Template policy (alpha)
+## Template policy
+
+> Template policies are currently an **alpha** feature.
 
 If you enable the use of workspace templates, a **template policy** allows you
-to control which fields users can set and which values can be used when they
-define their workspaces.
+to control which fields users can set and which values can they can use when
+defining their workspaces.
+
+Users can apply the following policies to fields:
+
+- `read` - **Default.** Workspaces cannot modify the field
+- `write` - Workspaces can overwrite the field
+- `append` - Workspaces can append lists (e.g., configure.start steps) or
+  mappings to the field
 
 The default template policy is as follows:
 
 ```yaml
 version: "0.2"
 workspace:
-    configure:
-        start:
-            policy: write
-    dev-urls:
+  configure:
+    start:
+      policy: write
+  dev-urls:
+    policy: write
+  specs:
+    kubernetes:
+      container-based-vm:
+        policy: write
+      cpu:
+        policy: write
+      disk:
         policy: write
-    specs:
-        kubernetes:
-            container-based-vm:
-                policy: write
-            cpu:
-                policy: write
-            disk:
-                policy: write
-            env:
-                policy: write
-            gpu-count:
-                policy: write
-            image:
-                policy: write
-            labels:
-                policy: read
-            memory:
-                policy: write
-            node-selector:
-                policy: read
-            tolerations:
-                policy: read
+      env:
+        policy: write
+      gpu-count:
+        policy: write
+      image:
+        policy: write
+      labels:
+        policy: read
+      memory:
+        policy: write
+      node-selector:
+        policy: read
+      tolerations:
+        policy: read
 ```
 
-Underneath the policy template preview, you can either upload your policy or you
-can drag-and-drop the file onto the UI. Click **Save** to persist your changes.
+Underneath the policy template preview, you can either upload your policy or
+drag-and-drop the file onto the UI. Click **Save** to persist your changes.
 
 If, at any time, you want to remove your policy and use Coder's default policy,
 click **Reset to default**.
 
+The template policy applies to all workspaces, including custom workspaces,
+created and managed in Coder. If a workspace's properties conflict with the
+template policy, Coder will ignore the workspace's values in favor of those
+defined by the template policy.
+
 ## Embeddable Button
 
-The Embeddable Button section features a form you can use for generating an embeddable
-button. This button makes it easy for developers to use your
+The **Embeddable Button** section features a form you can use for generating an
+embeddable button. This button makes it easy for developers to use your
 [workspace template](../workspaces/workspaces-as-code/index.md).
 
 To create your button:
@@ -82,4 +94,4 @@ By default, workspaces as code is an opt-in feature. To enable workspaces as
 code, go to **Admin > Templates** and set **Enable using Workspace Templates**
 to **On**.
 
-![toggle workspaces as code](../assets/admin/wac_toggle.png)
+![Toggle workspaces as code](../assets/wac_toggle.png)
