docs: clarify coder_metadata usage

ethanndickson · ethanndickson · commit ca52f1f8b308 · 2024-08-14T05:48:20.000Z
diff --git a/docs/resources/metadata.md b/docs/resources/metadata.md
@@ -3,12 +3,15 @@
 page_title: "coder_metadata Resource - terraform-provider-coder"
 subcategory: ""
 description: |-
-  Use this resource to attach metadata to a resource. They will be displayed in the Coder dashboard.
+  Use this resource to attach metadata to a resource. They will be displayed in the Coder dashboard alongside the resource. The resource containing the agent, and it's metadata, will be shown by default.
+  Alternatively, to attach metadata to the agent, use a metadata block within a coder_agent resource.
 ---
 
 # coder_metadata (Resource)
 
-Use this resource to attach metadata to a resource. They will be displayed in the Coder dashboard.
+Use this resource to attach metadata to a resource. They will be displayed in the Coder dashboard alongside the resource. The resource containing the agent, and it's metadata, will be shown by default. 
+
+Alternatively, to attach metadata to the agent, use a `metadata` block within a `coder_agent` resource.
 
 ## Example Usage
 
diff --git a/provider/metadata.go b/provider/metadata.go
@@ -14,7 +14,9 @@ func metadataResource() *schema.Resource {
 		SchemaVersion: 1,
 
 		Description: "Use this resource to attach metadata to a resource. They will be " +
-			"displayed in the Coder dashboard.",
+			"displayed in the Coder dashboard alongside the resource. " +
+			"The resource containing the agent, and it's metadata, will be shown by default. " + "\n\n" +
+			"Alternatively, to attach metadata to the agent, use a `metadata` block within a `coder_agent` resource.",
 		CreateContext: func(c context.Context, resourceData *schema.ResourceData, i interface{}) diag.Diagnostics {
 			resourceData.SetId(uuid.NewString())
 
