changes to ReadMe files, examples, schema descriptions in the GO file…

…s, sh and tf files.

README.md

@@ -1,6 +1,6 @@
 # Qwilt Terraform Provider
 
-> ⚠️ **Disclaimer**: the project is still in the 0.x.x version, which means it’s still in the experimental phase.
+> ⚠️ **Disclaimer**: This provider is currently in limited availability. 
 
 ## Requirements
 
@@ -9,8 +9,8 @@
 
 ## Building The Provider
 
-1. Clone the repository
-1. Enter the repository directory
+1. Clone the repository.
+1. Enter the repository directory.
 1. Build the provider using the Go `install` command:
 
 ```shell
@@ -35,7 +35,7 @@ Then commit the changes to `go.mod` and `go.sum`.
 
 ## Developing the Provider
 
-Configure `~/.terraformrc` with the name of your provider and go
+Configure `~/.terraformrc` with the name of your provider and Go
 installation. For example:
 
 ```
@@ -47,7 +47,7 @@ provider_installation {
 
   # For all other providers, install them directly from their origin provider
   # registries as normal. If you omit this, Terraform will _only_ use
-  # the dev_overrides block, and so no other providers will be available.
+  # the dev_overrides block, so no other providers will be available.
   direct {}
 }
 ```
@@ -62,7 +62,7 @@ To generate or update documentation, run `go generate`.
 
 In order to run the full suite of Acceptance tests, run `make testacc`.
 
-*Note:* Acceptance tests create real resources, and often cost money to run. Don'r run it on production environment.
+*Note:* Acceptance tests create real resources, and often cost money to run. Don't run them on a production environment.
 
 ```shell
 make testacc

examples/README.md

@@ -1,11 +1,14 @@
 # Examples
 
-This directory contains examples that are mostly used for documentation, but can also be run/tested manually via the Terraform CLI.
+The examples in this directory are mostly used to generate documentation, with the exception of the files under Playground (see below).
 
-The document generation tool looks for files in the following locations by default. All other *.tf files besides the ones mentioned below are ignored by the documentation tool. This is useful for creating examples that can run and/or ar testable even if some parts are not relevant for the documentation.
+The document generation tool looks for files in the following locations by default. All other *.tf files besides the ones mentioned below are ignored by the documentation tool. This is useful for creating examples that can run and/or are testable even if some parts are not relevant for the documentation.
 
 * **provider/provider.tf** example file for the provider index page
 * **data-sources/`full data source name`/data-source.tf** example file for the named data source page
 * **resources/`full resource name`/resource.tf** example file for the named data source page
 
-Run: go generate -v ./... to generate documentation
+Run: go generate -v ./... to generate documentation
+
+
+The sample configuration files under Playground demonstrate how to use the Qwilt Terraform provider. They can be used as starter files for provisioning and managing resources via the Terraform CLI. They are designed for customization-- replace placeholder values with your own specific configuration details. Replace the example certificate and key values with your own.

examples/playground/README.md

@@ -1,10 +1,13 @@
 # Qwilt Provider Usage Examples
 
-This directory contains examples that comprehensively demonstrate how to use Qwilt's Terraform Provider.  These examples demonstrate various common use cases.
+This examples in this directory demonstrate how to use the Qwilt Terraform Provider.  They cover various common use cases.
 
 Inside this directory, you will find the following examples:
-* *provider-install-verification*:  Very bare-bones example to verify that you have the Qwilt Terraform Provider installed correctly.
-* *qwilt-config-basic*:  A simple example with 1 site, site configuration, certificate, and activation resource.
-* *qwilt-config-multi*:  A more complex example involving 2 sites, site configurations, certificates, and activation resources.
-* *qwilt-config-multi-workspace*:  An advanced demonstration for how to use the Terraform workspaces capability to manage multiple instances of the same configuration.  This manages 2 configurations, and allows you to create production and non-production instances.
-* *qwilt-datasource*:  A practical demonstration of how to use the sites and certificates data sources to query for various resources.
+* *provider-install-verification*:  Demonstrates how to confirm that the Qwilt Terraform Provider is installed correctly.
+* *qwilt-config-basic*:  Demonstrates how to configure a single site, site configuration, certificate, and activation resource.
+* *qwilt-config-multi*: Demonstrates how to manage two sites, site configurations, certificates, and activation resources within a single Terraform configuration.
+* *qwilt-config-multi-workspace*: (Advanced) Demonstrates how to use the Terraform workspaces capability to manage multiple instances of the same configuration. Specifically, this example illustrates how to manage both production and non-production instances of a configuration that defines two sites.
+* *qwilt-datasource*:  A practical example demonstrating how to use the *sites* and *certificates* data sources to query various resources.
+
+
+**TIP:** The sample configuration files in this directory can also be used as starter files for provisioning and managing resources via the Terraform CLI. They are designed for customization-- replace placeholder values with your own specific configuration details. Replace the example certificate and key values with your own.

examples/playground/provider-install-verification/README.md

@@ -1,11 +1,15 @@
 # Qwilt Provider Install Verification
 
-This is a very trivial, bare-bones example to verify that you have the Qwilt Terraform Provider installed correctly.
+This is a minimal, verification-only example intended solely to confirm that the Qwilt Terraform Provider is installed correctly.
 
-First, make sure your QCDN_API_KEY env variable is set (this is the recommended method for authentication.
-See other authentication alternatives in details in the provider documentation.
+To use this example:
 
-To use it, run 'apply':
-```
-$ terraform apply
-```
+1. Make sure your QCDN_API_KEY env variable is set. (This is the recommended authentication method.)
+
+    For more information on authentication, see the provider documentation, which also covers alternative methods.
+
+2. Apply the configuration:
+
+    ```
+    $ terraform apply
+    ```

examples/playground/qwilt-config-basic/README.md

@@ -1,13 +1,21 @@
 # Qwilt Basic Resource Example
 
-This is a simple example demonstrating how to configure 1 site, site configuration, certificate, and activation resource.
+This is a simple example demonstrating how to configure a single site, site configuration, certificate, and activation resource.
 
-The example by default uses the embedded host_index JSON configuration in main.tf.  Optionally, this can be removed, and "examplesitejson.json" can be included instead to maintain the SVTA configuration in a separate file.
+In this example, the host_index JSON configuration is embedded in main.tf.  
 
-First, make sure your QCDN_API_KEY env variable is set (this is the recommended method for authentication.
-See other authentication alternatives in details in the provider documentation.
+If you prefer to maintain the SVTA configuration in a separate file, remove the embedded host_index, and use the reference to "examplesitebasic.json" ```host_index = file("./examplesitebasic.json")``` instead.
 
-To use it, define your API token and run 'apply':
-```
-$ terraform apply
-```
+To use this example:
+
+1. Make sure your QCDN_API_KEY env variable is set. (This is the recommended authentication method.)
+
+    For more information on authentication, see the provider documentation, which also covers alternative methods.
+
+2. Replace the placeholder values with your own specific configuration details. Replace the example certificate and key values with your own.
+
+3. Apply the configuration:
+
+    ```
+    $ terraform apply
+    ```

examples/playground/qwilt-config-basic/main.tf

@@ -43,7 +43,7 @@ resource "qwilt_cdn_site_configuration" "example" {
 	]
 }
 EOT
-  change_description = "Basic example demonstrating the Terraform plugin"
+  change_description = "Basic example demonstrating the Terraform plugin."
 }
 
 resource "qwilt_cdn_certificate" "example" {

examples/playground/qwilt-config-multi-workspace/README.md

@@ -1,47 +1,55 @@
 # Qwilt Multi-Config Resource Example Using Workspaces
 
-This is our most complex example.  If you are not comfortable with how to use the Qwilt Terraform Provider, we suggest reviewing some of the other examples first.
+⚠️This is our most complex example.  If you are not yet comfortable using the Qwilt Terraform Provider, we suggest reviewing the other examples first.
 
-This is an advanced demonstration for how to use the Terraform workspaces capability to manage multiple instances of the same configuration.  This example manages 2 configurations, and allows you to create production and non-production instances.  This strategy may be used to manage more complex workflows, where different teams (e.g. dev, qa, etc.) may need to work on different instances of a site.
+This example demonstrates how to use Terraform workspaces to manage multiple instances of the same configuration. Specifically, it illustrates how to manage both production and non-production instances of a Terraform configuration that defines two sites.
 
-This example may be more complex than your individual needs.  Qwilt's system provides a method for simple staging of sites for verification prior to production that does not require workspaces.  If your needs are more modest, we encourage you to try this staging capability instead.
+This approach is ideal for managing advanced use cases where different teams (e.g. dev, qa, etc.) need to work on different instances of a site.
 
-In this example, configurations are managed through separate Terraform configuration files (e.g. examplesite.tf and examplesite2.tf), and SVTA configurations are managed through corresponding JSON files that are included in the configuration.  Both the configuration and JSON configuration are templated to allow variable substitution based on what type of site is being managed.  Each site and instance has its own associated certificate and private key.
+If this level of complexity is not needed for your use case, Qwilt provides a simpler method for staging sites for verification before production that does not require workspaces.  For more straightforward requirements, we recommend using the staging capability.
 
-First, make sure your QCDN_API_KEY env variable is set (this is the recommended method for authentication.
-See other authentication alternatives in details in the provider documentation.
+Configurations are managed through separate Terraform configuration files (e.g. examplesite.tf and examplesite2.tf), and the SVTA configurations are managed through the corresponding JSON files (e.g. examplesite.json, examplesite2.json). Both the Terraform and JSON configuration are templated to allow variable substitution based on the type of site being managed. Each site and instance has its own associated certificate and private key.
 
-To get started, you must create your workspaces.  For example:
-```
-$ terraform workspace new prod
-Created and switched to workspace "prod"!
+To use this example:
 
-You're now on a new, empty workspace. Workspaces isolate their state,
-so if you run "terraform plan" Terraform will not see any existing state
-for this configuration.
+1. Make sure your QCDN_API_KEY env variable is set. (This is the recommended authentication method.)
 
-$ terraform workspace new dev
-Created and switched to workspace "dev"!
+    For more information on authentication, see the provider documentation, which also covers alternative methods. 
 
-You're now on a new, empty workspace. Workspaces isolate their state,
-so if you run "terraform plan" Terraform will not see any existing state
-for this configuration.
+2. Create your workspaces.  
 
-$ terraform workspace list
-  default
-* dev
-  prod
-```
+    For example, to create workspaces for production and development, run the following commands:
 
-Terraform will now track separate states for each of these environments.  You may now switch to an environment to operate within it.  This will switch to the production workspace so that you can apply the production configuration:
-```
-$ terraform workspace select prod
-Switched to workspace "prod".
-```
+    ```
+    $ terraform workspace new prod
+    Created and switched to workspace "prod"!
 
-Now, you may apply the configuration as follows:
-```
-$ terraform apply
-```
+      You're now in a new, empty workspace. Workspaces isolate their state, so when you run Terraform plan, Terraform will not detect any existing state for this configuration.
 
-The same may be done within the "dev" workspace.  Managing more than 2 workspaces (prod and non-prod) will require further changes to the configuration.
+    $ terraform workspace new dev
+    Created and switched to workspace "dev"!
+
+      You're now in a new, empty workspace. Workspaces isolate their state, so when you run terraform plan, Terraform will not detect any existing state for this configuration.
+
+   $ terraform workspace list
+      default
+   * dev
+      prod
+   ```
+
+    Terraform will now track separate states for each environment.  You must switch to an environment to operate within it. For example, to apply the production configuration, switch to the production workspace:
+
+   ```
+    $ terraform workspace select prod
+    Switched to workspace "prod".
+    ```
+
+3. Switch to the desired workspace and apply the configuration:
+
+    ```
+    $ terraform apply
+     ```
+
+    Repeat for the "dev" workspace if needed. 
+    
+  Managing more than two workspaces (e.g. additional non-production environments) requires further changes to the configuration.

examples/playground/qwilt-config-multi/README.md

@@ -1,13 +1,19 @@
 # Qwilt Multi-Config Resource Example
 
-This is a more complex example demonstrating how to manage 2 sites, site configurations, certificates, and activation resources in a single configuration.
+This is a more complex example demonstrating how to manage two sites, site configurations, certificates, and activation resources in a single configuration.
 
-Configurations are managed through separate Terraform configuration files (e.g. examplesite.tf and examplesite2.tf), and SVTA configurations are managed through corresponding JSON files that are included in the configuration.  Each site has its own associated certificate and private key.
+Configurations are managed through separate Terraform configuration files (e.g. examplesite.tf and examplesite2.tf), and the SVTA configurations are managed through the corresponding JSON files (e.g. examplesite.json, examplesite2.json) that are included in the configuration.  Each site has its own associated certificate and private key.
 
-First, make sure your QCDN_API_KEY env variable is set (this is the recommended method for authentication. 
-See other authentication alternatives in details in the provider documentation.
+To use this example:
 
-To use it, run 'apply':
-```
-$ terraform apply
-```
+1. Make sure your QCDN_API_KEY env variable is set. (This is the recommended authentication method.)
+
+    For more information on authentication, see the provider documentation, which also covers alternative methods.
+
+2. Replace the placeholder values with your own specific configuration details. Replace the example certificate and key values with your own.
+
+3. Apply the configuration:
+
+    ```
+    $ terraform apply
+    ```

examples/playground/qwilt-datasource/README.md

@@ -1,9 +1,9 @@
 # Qwilt Data Source Example
 
-This is a practical demonstration of how to use the sites and certificates data sources to query for various resources within your configuration.
+This is a practical example demonstrating how to use the *sites* and *certificates* data sources to query various resources within your configuration.
 
-First, make sure your QCDN_API_KEY env variable is set (this is the recommended method for authentication.
-See other authentication alternatives in details in the provider documentation.
+First, make sure the QCDN_API_KEY env variable is set. (This is the recommended authentication method.)
+For more information on authentication, see the provider documentation, which also covers alternative methods.
 
 By default, checking the plan will return an empty result:
 ```
@@ -12,51 +12,61 @@ $ terraform plan
 
 ## Site Lookup
 
-A common use case for using the data source is to find your site information so that you can import it into a Terraform configuration.  To search sites by name, you may do this:
-```
-$ terraform plan -var="site_name=example.com"
-```
-The command above will perform a substring match of the site_name attribute of each defined site and output matching site_id's.
+A common use case for using the data source is to find your site information so that you can import it into a Terraform configuration.  
+
+To search for a site by name, do this:
+    ```
+    $ terraform plan -var="site_name=example.com"
+    ```
+    The above command launches a substring match of the site_name attribute of each defined site and outputs the matching site_ids.
 
-If you prefer searching through a giant list of all sites, you may output all sites as follows:
-```
-$ terraform plan -var="site_id=all"
-```
+
+To retrieve a list of all sites, do this:
+
+    ```
+    $ terraform plan -var="site_id=all"
+    ```
 
 Once you have identified the site_id that you are targeting, you may search for it directly:
-```
-$ terraform plan -var="site_id=<SiteID>"
-```
-This will provide details about a specific site_id, and a list of associated site configurations (i.e. revisions) and publishing operations (i.e. site activations).
+
+    ```
+    $ terraform plan -var="site_id=<SiteID>"
+    ```
+
+   The output includes details about the specified site_id, and a list of associated site configurations (i.e. revisions) and publishing operations (i.e. site activations).
 
 ## Site Configuration and Activation Lookup
 
 To get details about a specific site configuration and/or publishing operation, you may use their specific variables:
 ```
 $ terraform plan -var="site_id=<SiteID>" -var="revision_id=<RevisionID>" -var="publish_id=<PublishID>"
 ```
-You may specific either revision_id, publish_id, or both.
+You may specify revision_id, publish_id, or both.
 
 ## Certificate Lookup
 
 The same logic can be applied to certificates.  Certificates can be queried by domain name and certificate ID.
 
-To search for certificates by domain name, you may do this:
-```
-$ terraform plan -var="cert_domain=example.com"
-```
-This command will perform a substring match of the cert_domain attribute for each defined certificate and output the matching cert_id's.
+To search for certificates by domain name:
+
+    ```
+    $ terraform plan -var="cert_domain=example.com"
+    ```
+    The above command launches a substring match of the cert_domain attribute for each defined certificate and outputs the matching cert_ids.
 
-If you prefer searching through a giant list of all certificates, you may output all certificates as follows:
-```
-$ terraform plan -var="cert_id=all"
-```
+
+To retrieve a list of all certificates, do this:
+
+    ```
+    $ terraform plan -var="cert_id=all"
+    ```
 
 Once you have identified the cert_id that you are targeting, you may search for it directly:
-```
-$ terraform plan -var="cert_id=<CertificateID>"
-```
-This will provide details about a specific cert_id.
+
+    ```
+    $ terraform plan -var="cert_id=<CertificateID>"
+    ```
+    The output provides details about the specified cert_id.
 
 ## About This Example