Merge pull request #122 from Resourcely-Inc/drbild/improve-documentation

Documenation improvements
Resourcely-Inc · Nov 26, 2024 · 6642434 · 6642434
2 parents 409b4bb + 9228a2a
commit 6642434
Show file tree

Hide file tree

Showing 48 changed files with 1,162 additions and 288 deletions.
diff --git a/docs/data-sources/blueprint.md b/docs/data-sources/blueprint.md
@@ -1,16 +1,27 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "resourcely_blueprint Data Source - terraform-provider-resourcely"
 subcategory: ""
-description: |-
-  A resourcely blueprint
 ---
 
 # resourcely_blueprint (Data Source)
 
-A resourcely blueprint
+A blueprint is a configuration template used to provision cloud infrastructure resources. Blueprints allow you to:
 
+- Define which options are available for properties of your resource(s).
+- Apply gaurdrails to your resource(s) to prevent misconfiguration.
+- Define what information to collect from your developers before provisioning the resource.
 
+Once a blueprint is configured and published, it becomes available for use in your Resourcely service catalog.
+
+The template is specified using Resourcely's TFT templating language. See the [Authoring Your Own Blueprints](https://docs.resourcely.io/build/setting-up-blueprints/authoring-your-own-blueprints) docs for details about TFT. The [Resourcely Foundry](https://portal.resourcely.io/foundry?mode=blueprint) provides an IDE to assist with authoring the template.
+
+## Example Usage
+
+```terraform
+data "resourcely_blueprint" "example" {
+  series_id = "00000000-00000000-00000000-00000000"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -19,20 +30,17 @@ A resourcely blueprint
 
 - `series_id` (String) UUID for the blueprint
 
-### Optional
-
-- `is_published` (Boolean) A published blueprint is available for use by developers to create resources through the Resourcely portal.
-
 ### Read-Only
 
-- `categories` (Set of String)
-- `cloud_provider` (String)
-- `content` (String)
-- `description` (String)
-- `excluded_context_question_series` (Set of String) series_id for context questions that won't be used with this blueprint, even if this blueprint matches the context questions' blueprint_categories
-- `guidance` (String)
-- `id` (String) UUID for this version.
-- `labels` (Set of String)
-- `name` (String)
+- `categories` (Set of String) The category to assign to this blueprint.
+- `cloud_provider` (String) The cloud provider that this blueprint targets.
+- `content` (String) The templated Terraform configuration specified using Resourcely's TFT format.
+- `description` (String) A description of the blueprints's purpose or functionality.
+- `excluded_context_question_series` (Set of String) The series_ids for context questions that won't be used with this blueprint, even if this blueprint matches the context questions' blueprint_categories
+- `guidance` (String) Guidance to help your users know when and how to use this blueprint.
+- `id` (String) UUID for the current version of the blueprint.
+- `is_published` (Boolean) A published blueprint is available for use by developers to create resources through the Resourcely portal.
+- `labels` (Set of String) Additional keywords to help your users discover this blueprint.
+- `name` (String) The name of the blueprint.
 - `scope` (String)
-- `version` (Number) Specific version of the blueprint
+- `version` (Number) Increment version number for the current version of the blueprint.
diff --git a/docs/data-sources/context_question.md b/docs/data-sources/context_question.md
@@ -1,42 +1,57 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "resourcely_context_question Data Source - terraform-provider-resourcely"
 subcategory: ""
-description: |-
-  A resourcely ContextQuestion
 ---
 
 # resourcely_context_question (Data Source)
 
-A resourcely ContextQuestion
+A [context question](https://docs.resourcely.io/concepts/other-features-and-settings/global-context-and-values) is used to gather data from developers before provisioning a resource. They are designed to gather and store insightful data related to the resource.
 
+Some examples include:
 
+- What type of data will be stored in this infrastructure?
+- What application is this infrastructure associated with?
+- What is the email address the person/team responsible for this infrastructure?
+
+Three types of context questions are supported:
+
+- Text
+- Single Choice
+- Multiple Choice
+
+## Example Usage
+
+```terraform
+data "resourcely_context_question" "example" {
+  series_id = "00000000-00000000-00000000-00000000"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `series_id` (String) UUID for the global context
+- `series_id` (String) UUID for the context question.
 
 ### Read-Only
 
-- `answer_choices` (Attributes Set) (see [below for nested schema](#nestedatt--answer_choices))
-- `answer_format` (String)
-- `blueprint_categories` (Set of String) Resource categories the context question applies to
-- `excluded_blueprint_series` (Set of String) series_id for Blueprints exempt from this context question even though those blueprints belong to the context question's blueprint_categories
-- `id` (String) UUID for this version.
-- `label` (String)
-- `priority` (Number) Priority of this question, relative to others. 0=high, 1=medium, 2=low
-- `prompt` (String)
-- `qtype` (String)
-- `regex_pattern` (String) Regex validation for the acceptable answers to the context question
+- `answer_choices` (Attributes Set) The answer choices from which the developer can select. Applicable only when `qtype` is `QTYPE_SINGLE_SELECT` or `QTYPE_MULTI_SELECT`. (see [below for nested schema](#nestedatt--answer_choices))
+- `answer_format` (String) A format validation for acceptable answers to the context question. Applicable only when `qtype` is `QTYPE_TEXT` . Will be one of `ANSWER_TEXT`, `ANSWER_NUMBER`, `ANSWER_EMAIL`, or `ANSWER_REGEX`. If `ANSWER_REGEX`, the `regex_pattern` property will also be set.
+- `blueprint_categories` (Set of String) The blueprint categories to which this context question applies. This question will be asked whenever a developer uses a blueprint in these categories.
+- `excluded_blueprint_series` (Set of String) The series_ids of blueprints for which this question should not be asked, even if those blueprints belong to the context question's blueprint_categories.
+- `id` (String) UUID for the current version of this context question.
+- `label` (String) A key used to reference the context question in blueprints and guardrails. Is unique within your Resourcley tenant.
+- `priority` (Number) The priority of this question, relative to others. 0=high, 1=medium, 2=low
+- `prompt` (String) The question that Resourcely will ask your developers.
+- `qtype` (String) The type of the question. Will be one of `QYTPE_TEXT`, `QYTPE_SINGLE_SELECT`, or `QTYPE_MULTI_SELECT`.
+- `regex_pattern` (String) A regex validation for the acceptable answers to the context question. Applicable only when both `qtype` is `QTYPE_TEXT` and `answer_format` is `ANSWER_REGEX`.
 - `scope` (String)
-- `version` (Number) Specific version of the global context
+- `version` (Number) Incrementing version number of the context question.
 
 <a id="nestedatt--answer_choices"></a>
 ### Nested Schema for `answer_choices`
 
 Read-Only:
 
-- `label` (String)
+- `label` (String) The value for the answer choice.
diff --git a/docs/data-sources/global_value.md b/docs/data-sources/global_value.md
@@ -1,49 +1,46 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "resourcely_global_value Data Source - terraform-provider-resourcely"
 subcategory: ""
-description: |-
-  A Resourcely global value
 ---
 
 # resourcely_global_value (Data Source)
 
-A Resourcely global value
+A [global value](https://docs.resourcely.io/concepts/other-features-and-settings/global-values) allows admins to define custom drop-downs for customizing Terraform infrastructure resource properties before they are provisioned.  They are useful for providing access to lists of relatively static values like VPC IDs, allowed regions, department or team names, etc.
 
+## Example Usage
 
+```terraform
+data "resourcely_global_value" "example" {
+  series_id = "00000000-00000000-00000000-00000000"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `series_id` (String) UUID for the global value
+- `series_id` (String) UUID for the global value.
 
 ### Read-Only
 
-- `description` (String) A longer description
-- `id` (String) UUID for this version.
-- `is_deprecated` (Boolean) True if the global value should not be used in new blueprints or guardrails
+- `description` (String) A description of the purpose of the global value.
+- `id` (String) UUID for the current version of the global value.
+- `is_deprecated` (Boolean) Set to true if the global value should not be used in new blueprints or guardrails
 - `key` (String) An immutable identifier used to reference this global value in blueprints or guardrails.
 
 Must start with a lowercase letter in `a-z` and include only characters in `a-z0-9_`.
-- `name` (String) A short display name
-- `options` (Attributes List) The list of value options for this global value (see [below for nested schema](#nestedatt--options))
-- `type` (String) The type of options in the global value. Can be one of `PRESET_VALUE_TEXT`, `PRESET_VALUE_NUMBER`, `PRESET_VALUE_LIST`, `PRESET_VALUE_OBJECT`
-- `version` (Number) Specific version of the global value
+- `name` (String) The name of the global value.
+- `options` (Attributes List) The list of value options for this global value. (see [below for nested schema](#nestedatt--options))
+- `type` (String) The type of options in the global value. Will be one of `PRESET_VALUE_TEXT`, `PRESET_VALUE_NUMBER`, `PRESET_VALUE_LIST`, `PRESET_VALUE_OBJECT`
+- `version` (Number) Incrementing version number for the current version of the global value.
 
 <a id="nestedatt--options"></a>
 ### Nested Schema for `options`
 
 Read-Only:
 
-- `description` (String) A longer description
-- `key` (String) An immutable identifier for ths option.
-
-Must start with a lowercase letter in `a-z` and include only characters in `a-z0-9_`.
-- `label` (String) A unique short display name
-- `value` (String) A JSON encoding of the option's value. This value must match the declared type of the global value.
-
-Example: `value = jsonencode("a")`
-
-Example: `value = jsonencode(["a", "b"])`
+- `description` (String) A description of this option's meaning.
+- `key` (String) An immutable identifier for ths option. Must start with a lowercase letter in `a-z` and include only characters in `a-z0-9_`.
+- `label` (String) A unique display name
+- `value` (String) A JSON encoding of the option's value.`
diff --git a/docs/data-sources/guardrail.md b/docs/data-sources/guardrail.md
@@ -1,36 +1,42 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "resourcely_guardrail Data Source - terraform-provider-resourcely"
 subcategory: ""
-description: |-
-  A resourcely guardrail
 ---
 
 # resourcely_guardrail (Data Source)
 
-A resourcely guardrail
+A guardrail governs how cloud resources can be created and altered, preventing infrastructure misconfiguration. Before infrastructure is provisioned, Resourcely examines the changes being made and prevents a merge if any guardrail requirements are violated. Some examples of guardrails include:
 
+- Require approval for making a public S3 bucket
+- Restrict the allowed compute instance types or images
 
+Guardrails are specified using the [Really policy language](https://docs.resourcely.io/build/setting-up-guardrails/authoring-your-own-guardrails).
+
+## Example Usage
+
+```terraform
+data "resourcely_guardrail" "example" {
+  series_id = "00000000-00000000-00000000-00000000"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `series_id` (String) UUID for the guardrail
+- `series_id` (String) UUID for the guardrail.
 
 ### Read-Only
 
-- `category` (String)
-- `cloud_provider` (String)
-- `content` (String)
-- `description` (String)
-- `guardrail_template_inputs` (String) A JSON encoding of values for the guardrail template inputs.
-
-Example: `guardrail_template_inputs = jsonencode({inputOne = "value one"})`
-- `guardrail_template_series_id` (String) The series id of the guardrail template used to render the policies
-- `id` (String) UUID for this version.
-- `name` (String)
+- `category` (String) The category of this guardrail.
+- `cloud_provider` (String) The cloud provider that this guardrail targets.
+- `content` (String) The guardrail policy written in the [Really policy language](https://docs.resourcely.io/build/setting-up-guardrails/authoring-your-own-guardrails).
+- `description` (String) A description of the guardrail's purpose or policy.
+- `guardrail_template_inputs` (String) A JSON encoding of values for the guardrail template inputs.`
+- `guardrail_template_series_id` (String) The series id of the guardrail template used to render the policy.
+- `id` (String) UUID for the current version of this guar.
+- `name` (String) The name of the guardrail.
 - `scope` (String)
-- `state` (String)
-- `version` (Number) Specific version of the guardrail
+- `state` (String) The [state](https://docs.resourcely.io/build/setting-up-guardrails/releasing-guardrails#guardrail-status) of the guardrail.
+- `version` (Number) Incrementing version number for this current version of the guardrail.