additional documentation for prebuilds

Author: SasSwart

docs/data-sources/workspace.md

@@ -69,9 +69,9 @@ resource "docker_container" "workspace" {
 - `access_port` (Number) The access port of the Coder deployment provisioning this workspace.
 - `access_url` (String) The access URL of the Coder deployment provisioning this workspace.
 - `id` (String) UUID of the workspace.
-- `is_prebuild` (Boolean) Whether the workspace is a prebuild.
+- `is_prebuild` (Boolean) Similar to `prebuild_count`, but a boolean value instead of a count. This is set to true if the workspace is a currently unassigned prebuild. Once the workspace is assigned, this value will be false.
 - `name` (String) Name of the workspace.
-- `prebuild_count` (Number) A computed count, equal to 1 if the workspace was prebuilt.
+- `prebuild_count` (Number) A computed count, equal to 1 if the workspace is a currently unassigned prebuild. Use this to conditionally act on the status of a prebuild. Actions that do not require user identity can be taken when this value is set to 1. Actions that should only be taken once the workspace has been assigned to a user may be taken when this value is set to 0.
 - `start_count` (Number) A computed count based on `transition` state. If `start`, count will equal 1.
 - `template_id` (String) ID of the workspace's template.
 - `template_name` (String) Name of the workspace's template.

docs/data-sources/workspace_preset.md

@@ -3,12 +3,12 @@
 page_title: "coder_workspace_preset Data Source - terraform-provider-coder"
 subcategory: ""
 description: |-
-  Use this data source to predefine common configurations for workspaces.
+  Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are not defined by the preset will still be configurable when creating a workspace.
 ---
 
 # coder_workspace_preset (Data Source)
 
-Use this data source to predefine common configurations for workspaces.
+Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are not defined by the preset will still be configurable when creating a workspace.
 
 ## Example Usage
 
@@ -34,20 +34,20 @@ data "coder_workspace_preset" "example" {
 
 ### Required
 
-- `name` (String) Name of the workspace preset.
-- `parameters` (Map of String) Parameters of the workspace preset.
+- `name` (String) The name of the workspace preset.
 
 ### Optional
 
-- `prebuilds` (Block Set, Max: 1) Prebuilds of the workspace preset. (see [below for nested schema](#nestedblock--prebuilds))
+- `parameters` (Map of String) Workspace parameters that will be set by the workspace preset. For simple templates that only need prebuilds, you may define a preset with zero parameters. Because workspace parameters may change between Coder template versions, preset parameters are allowed to define values for parameters that do not exist in the current template version.
+- `prebuilds` (Block Set, Max: 1) Prebuilt workspace configuration related to this workspace preset. Coder will build and maintain workspaces in reserve based on this configuration. When a user creates a new workspace using a preset, they will be assigned a prebuilt workspace, instead of waiting for a new workspace to build. (see [below for nested schema](#nestedblock--prebuilds))
 
 ### Read-Only
 
-- `id` (String) ID of the workspace preset.
+- `id` (String) The preset ID is automatically generated and may change between runs. It is recommended to use the `name` attribute to identify the preset.
 
 <a id="nestedblock--prebuilds"></a>
 ### Nested Schema for `prebuilds`
 
 Required:
 
-- `instances` (Number)
+- `instances` (Number) The number of workspaces to keep in reserve for this preset.

provider/workspace.go

@@ -94,7 +94,7 @@ func workspaceDataSource() *schema.Resource {
 			"prebuild_count": {
 				Type:        schema.TypeInt,
 				Computed:    true,
-				Description: "A computed count, equal to 1 if the workspace was prebuilt.",
+				Description: "A computed count, equal to 1 if the workspace is a currently unassigned prebuild. Use this to conditionally act on the status of a prebuild. Actions that do not require user identity can be taken when this value is set to 1. Actions that should only be taken once the workspace has been assigned to a user may be taken when this value is set to 0.",
 			},
 			"start_count": {
 				Type:        schema.TypeInt,
@@ -114,7 +114,7 @@ func workspaceDataSource() *schema.Resource {
 			"is_prebuild": {
 				Type:        schema.TypeBool,
 				Computed:    true,
-				Description: "Whether the workspace is a prebuild.",
+				Description: "Similar to `prebuild_count`, but a boolean value instead of a count. This is set to true if the workspace is a currently unassigned prebuild. Once the workspace is assigned, this value will be false.",
 			},
 			"name": {
 				Type:        schema.TypeString,

provider/workspace_preset.go

@@ -23,7 +23,7 @@ func workspacePresetDataSource() *schema.Resource {
 	return &schema.Resource{
 		SchemaVersion: 1,
 
-		Description: "Use this data source to predefine common configurations for workspaces.",
+		Description: "Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are not defined by the preset will still be configurable when creating a workspace.",
 		ReadContext: func(ctx context.Context, rd *schema.ResourceData, i interface{}) diag.Diagnostics {
 			var preset WorkspacePreset
 			err := mapstructure.Decode(struct {
@@ -52,18 +52,18 @@ func workspacePresetDataSource() *schema.Resource {
 		Schema: map[string]*schema.Schema{
 			"id": {
 				Type:        schema.TypeString,
-				Description: "ID of the workspace preset.",
+				Description: "The preset ID is automatically generated and may change between runs. It is recommended to use the `name` attribute to identify the preset.",
 				Computed:    true,
 			},
 			"name": {
 				Type:         schema.TypeString,
-				Description:  "Name of the workspace preset.",
+				Description:  "The name of the workspace preset.",
 				Required:     true,
 				ValidateFunc: validation.StringIsNotEmpty,
 			},
 			"parameters": {
 				Type:        schema.TypeMap,
-				Description: "Parameters of the workspace preset.",
+				Description: "Workspace parameters that will be set by the workspace preset. For simple templates that only need prebuilds, you may define a preset with zero parameters. Because workspace parameters may change between Coder template versions, preset parameters are allowed to define values for parameters that do not exist in the current template version.",
 				Optional:    true,
 				Elem: &schema.Schema{
 					Type:         schema.TypeString,
@@ -73,13 +73,14 @@ func workspacePresetDataSource() *schema.Resource {
 			},
 			"prebuilds": {
 				Type:        schema.TypeSet,
-				Description: "Prebuilds of the workspace preset.",
+				Description: "Prebuilt workspace configuration related to this workspace preset. Coder will build and maintain workspaces in reserve based on this configuration. When a user creates a new workspace using a preset, they will be assigned a prebuilt workspace, instead of waiting for a new workspace to build.",
 				Optional:    true,
 				MaxItems:    1,
 				Elem: &schema.Resource{
 					Schema: map[string]*schema.Schema{
 						"instances": {
 							Type:         schema.TypeInt,
+							Description:  "The number of workspaces to keep in reserve for this preset.",
 							Required:     true,
 							ForceNew:     true,
 							ValidateFunc: validation.IntAtLeast(0),