Resource Docs cleanup - For Clinton's Review

Signed-off-by: Deepa Kumaraswamy <[email protected]>

docs-chef-io/content/inspec/resources/azure_active_directory_domain_service.md

@@ -43,7 +43,7 @@ Either one of the following parameters is mandatory.
 : The fully qualified name of the domain. Key, immutable, not nullable, unique.
 
 `authenticationType`
-: Indicates the configured authentication type for the domain.The value is either `Managed` or `Federated`.
+: Indicates the configured authentication type for the domain. The value is either `Managed` or `Federated`.
 
 `availabilityStatus`
 : This property is always `null` except when the verify action is used.
@@ -52,10 +52,10 @@ Either one of the following parameters is mandatory.
 : The value of the property is `false` if the DNS record management of the domain has been delegated to Microsoft 365.
 
 `isDefault`
-: `true` if this is the default domain that is used for user creation. There is only one default domain per company. Not nullable.
+: `true` if this is the default domain used for user creation. There is only one default domain per company. Not nullable.
 
 `isInitial`
-: `true` if this is the initial domain created by Microsoft Online Services (companyname.onmicrosoft.com). There is only one initial domain per company.
+: `true` if this is the initial domain created by Microsoft Online Services (`companyname.microsoft.com`). There is only one initial domain per company.
 
 `isRoot`
 : `true` if the domain is a verified root domain. Otherwise, `false` if the domain is a subdomain or unverified.
@@ -64,10 +64,10 @@ Either one of the following parameters is mandatory.
 : `true` if the domain has completed domain ownership verification.
 
 `passwordNotificationWindowInDays`
-: Specifies the number of days before a user receives notification that their password will expire. If the property is not set, a default value of 14 days will be used.
+: Specifies the number of days before a user receives a password expiry notification. A default value of 14 days is used if the property is not set.
 
 `passwordValidityPeriodInDays`
-: Specifies the length of time that a password is valid before it must be changed. If the property is not set, a default value of 90 days will be used.
+: Specifies the length of time that a password is valid before it must be changed. A default value of 90 days is used if the property is not set.
 
 `supportedServices`
 : The capabilities assigned to the domain.
@@ -77,15 +77,15 @@ Either one of the following parameters is mandatory.
 
 ## Examples
 
-**Test If an Active Directory Domain is Referenced with a Valid ID.**
+### Test to ensure if an active directory domain is referenced with a Valid ID
 
 ```ruby
 describe azure_active_directory_domain_service(id: 'example.com') do
   it { should exist }
 end
 ```
 
-**Test If an Active Directory Domain is Referenced with an Invalid ID.**
+### Test to ensure if an active directory domain is referenced with an Invalid ID
 
 ```ruby
 describe azure_active_directory_domain_service(id: 'example.com') do
@@ -97,7 +97,7 @@ end
 
 {{% inspec_matchers_link %}}
 
-### exists
+### Exists
 
 ```ruby
 describe azure_active_directory_domain_service(id: 'example.onmicrosoft.com') do
@@ -107,5 +107,4 @@ end
 
 ## Azure Permissions
 
-Graph resources require specific privileges granted to your service principal.
-Please refer to the [Microsoft Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-integrating-applications#updating-an-application) for information on how to grant these permissions to your application.
+Graph resources require specific privileges granted to your service principal. Please refer to the [Microsoft Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-integrating-applications#updating-an-application) for information on how to grant these permissions to your application.

docs-chef-io/content/inspec/resources/azure_active_directory_domain_services.md

@@ -35,7 +35,7 @@ end
 The following parameters can be passed for targeting specific domains.
 
 `filter`
-: A hash containing the filtering options and their values. The `starts_with_` operator can be used for fuzzy string matching. Parameter names are in snake case.
+: A hash containing the filtering options and their values. The `starts_with_` operator can be used for fuzzy string matching. Parameter names are in the snake case.
 
 : **Example**: `{ starts_with_given_name: 'J', starts_with_department: 'Core', country: 'United Kingdom', given_name: John}`
 
@@ -44,7 +44,7 @@ The following parameters can be passed for targeting specific domains.
 
 : **Example**: `"startswith(displayName,'J') and surname eq 'Doe'"` or `"userType eq 'Guest'"`
 
-It is advised to use these parameters to narrow down the targeted resources at the server side, Azure Graph API, for a more efficient test.
+It is advised to use these parameters to narrow down the targeted resources at the server-side, Azure Graph API, for a more efficient test.
 
 ## Properties
 
@@ -64,7 +64,7 @@ It is advised to use these parameters to narrow down the targeted resources at t
 : **Field**: `availabilityStatus`
 
 `is_admin_manageds`
-: A list of admin managed configuration.
+: A list of admin-managed configuration.
 
 : **Field**: `isAdminManaged`
 
@@ -114,23 +114,23 @@ It is advised to use these parameters to narrow down the targeted resources at t
 
 The following examples show how to use this InSpec audit resource.
 
-**Check domains with some filtering parameters applied at server side using `filter`.**
+### Test to ensure domains with some filtering parameters are applied at server side using `filter`
 
 ```ruby
 describe azure_active_directory_domain_services(filter: {authenticationType: "authenticationType-value"}) do
   it { should exist }
 end
 ```
 
-**Check domains with some filtering parameters applied at server side using `filter_free_text`.**
+### Test to ensure domains with some filtering parameters are applied at the server side using `filter_free_text`
 
 ```ruby
 describe azure_active_directory_domain_services(filter_free_text: "startswith(authenticationType,'authenticationType-value')") do
   it { should exist }
 end
 ```
 
-**Ensure there are supported services using client-side filtering.**
+### Test to ensure there are supported services using client-side filtering
 
 ```ruby
 describe azure_active_directory_domain_services.supportedServices do
@@ -142,9 +142,9 @@ end
 
 {{% inspec_matchers_link %}}
 
-### exists
+### Exists
 
-The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
+The control passes if the filter returns at least one result. Use `should_not` if you expect zero matches.
 
 ```ruby
 describe azure_active_directory_domain_services do
@@ -154,5 +154,4 @@ end
 
 ## Azure Permissions
 
-Graph resources require specific privileges granted to your service principal.
-Please refer to the [Microsoft Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-integrating-applications#updating-an-application) for information on how to grant these permissions to your application.
+Graph resources require specific privileges granted to your service principal. Please refer to the [Microsoft Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-integrating-applications#updating-an-application) for information on how to grant these permissions to your application.

docs-chef-io/content/inspec/resources/azure_aks_cluster.md

@@ -10,7 +10,7 @@ identifier = "inspec/resources/azure/azure_aks_cluster Resource"
 parent = "inspec/resources/azure"
 +++
 
-Use the `azure_aks_cluster` InSpec audit resource to test properties of an Azure AKS Cluster.
+Use the `azure_aks_cluster` InSpec audit resource to test the properties of an Azure AKS Cluster.
 
 ## Azure REST API Version, Endpoint, and HTTP Client Parameters
 
@@ -22,12 +22,14 @@ Use the `azure_aks_cluster` InSpec audit resource to test properties of an Azure
 
 ## Syntax
 
-An `azure_aks_cluster` resource block identifies an AKS Cluster by `name` and `resource_group` or the `resource_id`.
+An `azure_aks_cluster` resource block identifies an AKS Cluster by `name` and `resource_group`, or the `resource_id`.
+
 ```ruby
-describe azure_aks_cluster(resource_group: 'example', name: 'ClusterName') do
+describe azure_aks_cluster(resource_group: 'RESOURCE_GROUP', name: 'CLUSTER_NAME') do
   it { should exist }
 end
 ```
+
 ```ruby
 describe azure_aks_cluster(resource_id: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.ContainerService/managedClusters/{ClusterName}') do
   it { should exist }
@@ -37,17 +39,18 @@ end
 ## Parameters
 
 `resource_group`
-: Azure resource group that the targeted resource resides in. `MyResourceGroup`.
+: Azure resource group where the targeted resource resides.
 
 `name`
-: Name of the AKS cluster to test. `ClusterName`.
+: Name of the AKS cluster to test.
 
 `resource_id`
 : The unique resource ID. `/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.ContainerService/managedClusters/{ClusterName}`.
 
-Either one of the parameter sets can be provided for a valid query:
+Either one of the following parameter sets can be provided for a valid query:
+
 - `resource_id`
-- `resource_group` and `name`
+- `resource_group` and `name`.
 
 ## Properties
 
@@ -66,70 +69,76 @@ Either one of the parameter sets can be provided for a valid query:
 `disabled_logging_types`
 : The logging types that are disabled for the AKS cluster.
 
-For properties applicable to all resources, such as `type`, `name`, `id`, `properties`, refer to [`azure_generic_resource`]({{< relref "azure_generic_resource.md#properties" >}}).
+For properties applicable to all resources, such as `type`, `name`, `id`, and `properties`, refer to [`azure_generic_resource`]({{< relref "azure_generic_resource.md#properties" >}}).
+
+Also, refer to [Azure documentation](https://docs.microsoft.com/en-us/rest/api/aks/managedclusters/get#managedcluster) for other properties available.
 
-Also, refer to [Azure documentation](https://docs.microsoft.com/en-us/rest/api/aks/managedclusters/get#managedcluster) for other properties available. 
 Any attribute in the response may be accessed with the key names separated by dots (`.`).
 
 ## Examples
 
-**Test that an AKS Cluster has the Desired Network Plug-in.**
+### Test to ensure that an AKS Cluster has the desired network plug-in
 
 ```ruby
-describe azure_aks_cluster(resource_group: 'example', name: 'ClusterName') do
+describe azure_aks_cluster(resource_group: 'RESOURCE_GROUP', name: 'CLUSTER_NAME') do
   its('properties.networkProfile.networkPlugin') { should cmp 'kubenet' }
 end
 ```
 
-**Loop through All Clusters within The Subscription.**
+### Test to loop through all clusters within the subscription
 
 ```ruby
 azure_aks_clusters.ids.each do |resource_id|
   describe azure_aks_cluster(resource_id: resource_id) do
     its('properties.networkProfile.networkPlugin') { should cmp 'kubenet' }
   end
-end 
+end
 ```
 
-**Test that a Specified AKS Cluster has the Correct Number of Nodes in Pool.**
+### Test to ensure a specified AKS Cluster has the correct number of nodes in the pool
 
 ```ruby
-describe azure_aks_cluster(resource_group: 'example', name: 'ClusterName') do
+describe azure_aks_cluster(resource_group: 'RESOURCE_GROUP', name: 'CLUSTER_NAME') do
   its('properties.agentPoolProfiles.first.count') { should cmp 5 }
 end
 ```
 
-**Test that a Specified AKS Cluster has kube-audit logging enabled.**
+### Test to ensure a specified AKS Cluster has kube-audit logging enabled
 
 ```ruby
-describe azure_aks_cluster(resource_group: 'example', name: 'ClusterName') do
+describe azure_aks_cluster(resource_group: 'RESOURCE_GROUP', name: 'CLUSTER_NAME') do
   its('enabled_logging_types') { should include "kube-audit" }
 end
 ```
 
-**Test that a Specified AKS Cluster has logging enabled on it and no forms of logging disabled.**
+### Test to ensure a specified AKS Cluster has logging enabled on it and no forms of logging disabled
 
 ```ruby
-describe azure_aks_cluster(resource_group: 'example', name: 'ClusterName') do
+describe azure_aks_cluster(resource_group: 'RESOURCE_GROUP', name: 'CLUSTER_NAME') do
   its('disabled_logging_types.count') { should eq 0 }
 end
 ```
+
 See [integration tests](../../test/integration/verify/controls/azurerm_aks_cluster.rb) for more examples.
 
 ## Matchers
 
 This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [Universal Matchers page](https://docs.chef.io/inspec/matchers/).
 
-### exists
+### Exists
 
 ```ruby
 # If we expect 'ClusterName' to always exist
-describe azure_aks_cluster(resource_group: 'example', name: 'ClusterName') do
+describe azure_aks_cluster(resource_group: 'RESOURCE_GROUP', name: 'CLUSTER_NAME') do
   it { should exist }
 end
+```
 
-# If we expect 'ClusterName' to never exist
-describe azure_aks_cluster(resource_group: 'example', name: 'ClusterName') do
+### Not Exists
+
+```ruby
+# If we expect 'ClusterName' to not exist
+describe azure_aks_cluster(resource_group: 'RESOURCE_GROUP', name: 'CLUSTER_NAME') do
   it { should_not exist }
 end
 ```

docs-chef-io/content/inspec/resources/azure_aks_clusters.md

@@ -22,7 +22,7 @@ Use the `azure_aks_clusters` InSpec audit resource to test properties and config
 
 ## Syntax
 
-An `azure_aks_clusters` resource block returns all AKS Clusters, either within a Resource Group (if provided), or within an entire Subscription.
+An `azure_aks_clusters` resource block returns all AKS Clusters, either within a resource group (if provided) or an entire subscription.
 
 ```ruby
 describe azure_aks_clusters do
@@ -33,7 +33,7 @@ end
 or
 
 ```ruby
-describe azure_aks_clusters(resource_group: 'my-rg') do
+describe azure_aks_clusters(resource_group: 'RESOURCE_GROUP') do
   #...
 end
 ```
@@ -47,7 +47,7 @@ end
 ## Properties
 
 `ids`
-: A list of the unique resource ids.
+: A list of the unique resource IDs.
 
 : **Field**: `id`
 
@@ -78,27 +78,31 @@ end
 **Test that an Example Resource Group has the Named AKS Cluster.**
 
 ```ruby
-describe azure_aks_clusters(resource_group: 'ExampleGroup') do
-  its('names') { should include('ClusterName') }
+describe azure_aks_clusters(resource_group: 'RESOURCE_GROUP') do
+  its('names') { should include('CLUSTER_NAME') }
 end
 ```
 
 ## Matchers
 
 {{% inspec_matchers_link %}}
 
-### exists
+### Exists
 
-The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
+The control passes if the filter returns at least one result. Use `should_not` if you expect zero matches.
 
 ```ruby
 # If we expect 'ExampleGroup' Resource Group to have AKS Clusters
-describe azure_aks_clusters(resource_group: 'ExampleGroup') do
+describe azure_aks_clusters(resource_group: 'RESOURCE_GROUP') do
   it { should exist }
 end
+```
+
+### Not Exists
 
+```ruby
 # If we expect 'EmptyExampleGroup' Resource Group to not have AKS Clusters
-describe azure_aks_clusters(resource_group: 'EmptyExampleGroup') do
+describe azure_aks_clusters(resource_group: 'EMPTY_RESOURCE_GROUP') do
   it { should_not exist }
 end
 ```