Quality updates to documentation #2570

docs/CHANGELOG-v1.md

@@ -33,6 +33,12 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
 
 ## Unreleased
 
+What's changed since v1.36.0:
+
+- General improvements:
+  - Quality updates to documentation by @BernieWhite.
+    [#2570](https://github.com/Azure/PSRule.Rules.Azure/issues/2570)
+
 ## v1.36.0
 
 What's changed since v1.35.3:

docs/en/rules/Azure.ADX.SLA.md

@@ -1,8 +1,8 @@
 ---
-reviewed: 2022-01-18
+reviewed: 2024-05-01
 severity: Important
 pillar: Reliability
-category: Requirements
+category: RE:04 Target metrics
 resource: Data Explorer
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.ADX.SLA/
 ---
@@ -29,41 +29,41 @@ Consider using a production ready SKU that includes a SLA.
 
 To deploy clusters that pass this rule:
 
-- Set `sku.tier` to `Standard`.
-- Set `sku.name` to non-development SKU such as `Standard_D11_v2`.
+- Set the `sku.tier` property to `Standard`.
+- Set the `sku.name` property to non-development SKU such as `Standard_D11_v2`.
 
 For example:
 
 ```json
 {
-    "type": "Microsoft.Kusto/clusters",
-    "apiVersion": "2021-08-27",
-    "name": "[parameters('name')]",
-    "location": "[parameters('location')]",
-    "sku": {
-        "name": "Standard_D11_v2",
-        "tier": "Standard"
-    },
-    "identity": {
-        "type": "SystemAssigned"
-    },
-    "properties": {
-        "enableDiskEncryption": true
-    }
+  "type": "Microsoft.Kusto/clusters",
+  "apiVersion": "2023-08-15",
+  "name": "[parameters('name')]",
+  "location": "[parameters('location')]",
+  "sku": {
+    "name": "Standard_D11_v2",
+    "tier": "Standard"
+  },
+  "identity": {
+    "type": "SystemAssigned"
+  },
+  "properties": {
+    "enableDiskEncryption": true
+  }
 }
 ```
 
 ### Configure with Bicep
 
 To deploy clusters that pass this rule:
 
-- Set `sku.tier` to `Standard`.
-- Set `sku.name` to non-development SKU such as `Standard_D11_v2`.
+- Set the `sku.tier` property to `Standard`.
+- Set the `sku.name` property to non-development SKU such as `Standard_D11_v2`.
 
 For example:
 
 ```bicep
-resource adx 'Microsoft.Kusto/clusters@2021-08-27' = {
+resource adx 'Microsoft.Kusto/clusters@2023-08-15' = {
   name: name
   location: location
   sku: {
@@ -81,6 +81,6 @@ resource adx 'Microsoft.Kusto/clusters@2021-08-27' = {
 
 ## LINKS
 
-- [Target and non-functional requirements](https://learn.microsoft.com/azure/architecture/framework/resiliency/design-requirements#availability-targets)
+- [RE:04 Target metrics](https://learn.microsoft.com/azure/well-architected/reliability/metrics)
 - [Azure Data Explorer pricing](https://azure.microsoft.com/pricing/details/data-explorer/)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.kusto/clusters)

docs/en/rules/Azure.AKS.UptimeSLA.md

@@ -2,7 +2,7 @@
 reviewed: 2023-15-05
 severity: Important
 pillar: Reliability
-category: Requirements
+category: RE:04 Target metrics
 resource: Azure Kubernetes Service
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.AKS.UptimeSLA/
 ---
@@ -21,9 +21,12 @@ The `Standard` tier is suitable for financially backed SLA scenarios as it enabl
 
 Benefits:
 
-- The Free tier SKU imposes in-flight request limits of 50 mutating and 100 read-only calls. The Standard tier SKU automatically scales out based on the load.
-- The Free tier SKU is recommended only for cost-sensitive non-production workloads with 10 or fewer agent nodes. The Standard tier SKU configures more resources for the control plane and will dynamically scale to handle the request load from more nodes.
-- AKS recommends the use of the Standard tier for production workloads to ensure availability of control plane components. Clusters on the Free tier, by contrast come with limited resources for the control plane and are not suitable for production workloads.
+- The Free tier SKU imposes in-flight request limits of 50 mutating and 100 read-only calls.
+  The Standard tier SKU automatically scales out based on the load.
+- The Free tier SKU is recommended only for cost-sensitive non-production workloads with 10 or fewer agent nodes.
+  The Standard tier SKU configures more resources for the control plane and will dynamically scale to handle the request load from more nodes.
+- AKS recommends the use of the Standard tier for production workloads to ensure availability of control plane components.
+  Clusters on the Free tier, by contrast come with limited resources for the control plane and are not suitable for production workloads.
 - Uptime SLA guarantees 99.95% availability of the Kubernetes API server endpoint for clusters that use Availability Zones.
 - Uptime SLA guarantees 99.9% of availability for clusters that don't use Availability Zones.
 - AKS uses master node replicas across update and fault domains to ensure SLA requirements are met.
@@ -38,7 +41,7 @@ Consider enabling Uptime SLA for a financially backed SLA.
 
 To deploy an AKS cluster that pass this rule:
 
-- Set `sku.tier` to `Standard`.
+- Set the `sku.tier` property to `Standard`.
 
 For example:
 
@@ -85,7 +88,7 @@ For example:
 
 To deploy an AKS cluster that pass this rule:
 
-- Set `sku.tier` to `Standard`.
+- Set the `sku.tier` property to `Standard`.
 
 For example:
 
@@ -128,11 +131,12 @@ resource aks 'Microsoft.ContainerService/managedClusters@2023-02-01' = {
 
 ## NOTES
 
-`Basic` and `Paid` are removed in the `2023-02-01` and `2023-02-02 Preview` API version, and this will be a breaking change in API versions `2023-02-01` and `2023-02-02 Preview` or newer.
+`Basic` and `Paid` are removed in the `2023-02-01` and `2023-02-02 Preview` API version,
+and this will be a breaking change in API versions `2023-02-01` and `2023-02-02 Preview` or newer.
 
 ## LINKS
 
-- [Target and non-functional requirements](https://learn.microsoft.com/azure/architecture/framework/resiliency/design-requirements)
+- [RE:04 Target metrics](https://learn.microsoft.com/azure/well-architected/reliability/metrics)
 - [Azure Kubernetes Service (AKS) Uptime SLA](https://learn.microsoft.com/azure/aks/free-standard-pricing-tiers#uptime-sla-terms-and-conditions)
 - [Free and Standard pricing tiers for Azure Kubernetes Service (AKS) cluster management](https://learn.microsoft.com/azure/aks/free-standard-pricing-tiers)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.containerservice/managedclusters#managedclustersku)

docs/en/rules/Azure.SignalR.SLA.md

@@ -1,8 +1,8 @@
 ---
-reviewed: 2022-03-15
+reviewed: 2024-05-01
 severity: Important
 pillar: Reliability
-category: Requirements
+category: RE:04 Target metrics
 resource: SignalR Service
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.SignalR.SLA/
 ---
@@ -21,7 +21,7 @@ SignalR Services offer a range of SKU offerings:
 - `Free` - Are designed for early non-production use and do not include any SLA.
 - `Standard` - Are designed for production use and include an SLA.
 - `Premium` - Are designed for production use and include an SLA.
-  Additional, Premium SKUs support increased resilience with Availablity Zones.
+  Additional, Premium SKUs support increased resilience with Availability Zones.
 
 ## RECOMMENDATION
 
@@ -33,45 +33,45 @@ Consider using a Standard or Premium SKU that includes an SLA.
 
 To deploy services that pass this rule:
 
-- Set `sku.name` to `Standard_S1` or `Premium_P1`.
+- Set the `sku.name` property to `Standard_S1` or `Premium_P1`.
 
 For example:
 
 ```json
 {
-    "type": "Microsoft.SignalRService/signalR",
-    "apiVersion": "2021-10-01",
-    "name": "[parameters('name')]",
-    "location": "[parameters('location')]",
-    "kind": "SignalR",
-    "sku": {
-        "name": "Standard_S1"
-    },
-    "identity": {
-        "type": "SystemAssigned"
-    },
-    "properties": {
-        "disableLocalAuth": true,
-        "features": [
-            {
-                "flag": "ServiceMode",
-                "value": "Serverless"
-            }
-        ]
-    }
+  "type": "Microsoft.SignalRService/signalR",
+  "apiVersion": "2023-02-01",
+  "name": "[parameters('name')]",
+  "location": "[parameters('location')]",
+  "kind": "SignalR",
+  "sku": {
+    "name": "Standard_S1"
+  },
+  "identity": {
+    "type": "SystemAssigned"
+  },
+  "properties": {
+    "disableLocalAuth": true,
+    "features": [
+      {
+        "flag": "ServiceMode",
+        "value": "Serverless"
+      }
+    ]
+  }
 }
 ```
 
 ### Configure with Bicep
 
 To deploy services that pass this rule:
 
-- Set `sku.name` to `Standard_S1` or `Premium_P1`.
+- Set the `sku.name` property to `Standard_S1` or `Premium_P1`.
 
 For example:
 
 ```bicep
-resource service 'Microsoft.SignalRService/signalR@2021-10-01' = {
+resource service 'Microsoft.SignalRService/signalR@2023-02-01' = {
   name: name
   location: location
   kind: 'SignalR'
@@ -95,6 +95,6 @@ resource service 'Microsoft.SignalRService/signalR@2021-10-01' = {
 
 ## LINKS
 
-- [Target and non-functional requirements](https://learn.microsoft.com/azure/architecture/framework/resiliency/design-requirements#availability-targets)
+- [RE:04 Target metrics](https://learn.microsoft.com/azure/well-architected/reliability/metrics)
 - [Azure SignalR Service pricing](https://azure.microsoft.com/pricing/details/signalr-service/)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.signalrservice/signalr)

docs/en/rules/Azure.WebPubSub.SLA.md

@@ -2,7 +2,7 @@
 reviewed: 2023-07-09
 severity: Important
 pillar: Reliability
-category: Requirements
+category: RE:04 Target metrics
 resource: Web PubSub Service
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.WebPubSub.SLA/
 ---
@@ -31,38 +31,38 @@ Consider using a Standard SKU that includes an SLA.
 
 To deploy services that pass this rule:
 
-- Set `sku.name` to `Standard_S1`.
+- Set the `sku.name` property to `Standard_S1`.
 
 For example:
 
 ```json
 {
-    "type": "Microsoft.SignalRService/webPubSub",
-    "apiVersion": "2021-10-01",
-    "name": "[parameters('name')]",
-    "location": "[parameters('location')]",
-    "sku": {
-        "name": "Standard_S1"
-    },
-    "identity": {
-        "type": "SystemAssigned"
-    },
-    "properties": {
-        "disableLocalAuth": true
-    }
+  "type": "Microsoft.SignalRService/webPubSub",
+  "apiVersion": "2023-02-01",
+  "name": "[parameters('name')]",
+  "location": "[parameters('location')]",
+  "sku": {
+    "name": "Standard_S1"
+  },
+  "identity": {
+    "type": "SystemAssigned"
+  },
+  "properties": {
+    "disableLocalAuth": true
+  }
 }
 ```
 
 ### Configure with Bicep
 
 To deploy services that pass this rule:
 
-- Set `sku.name` to `Standard_S1`.
+- Set the `sku.name` property to `Standard_S1`.
 
 For example:
 
 ```bicep
-resource service 'Microsoft.SignalRService/webPubSub@2021-10-01' = {
+resource service 'Microsoft.SignalRService/webPubSub@2023-02-01' = {
   name: name
   location: location
   sku: {
@@ -79,6 +79,6 @@ resource service 'Microsoft.SignalRService/webPubSub@2021-10-01' = {
 
 ## LINKS
 
-- [Target and non-functional requirements](https://learn.microsoft.com/azure/architecture/framework/resiliency/design-requirements#availability-targets)
+- [RE:04 Target metrics](https://learn.microsoft.com/azure/well-architected/reliability/metrics)
 - [Azure Web PubSub pricing](https://azure.microsoft.com/pricing/details/web-pubsub/)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.signalrservice/webpubsub)

docs/examples-adx.bicep

@@ -9,8 +9,8 @@ param name string
 @description('The location resources will be deployed.')
 param location string = resourceGroup().location
 
-// An example data explorer cluster
-resource adx 'Microsoft.Kusto/clusters@2021-08-27' = {
+@description('An example data explorer cluster using a managed identity.')
+resource adx 'Microsoft.Kusto/clusters@2023-08-15' = {
   name: name
   location: location
   sku: {

docs/examples-adx.json

@@ -4,8 +4,8 @@
   "metadata": {
     "_generator": {
       "name": "bicep",
-      "version": "0.4.1124.51302",
-      "templateHash": "4543504609136927924"
+      "version": "0.26.170.59819",
+      "templateHash": "8842866449520651169"
     }
   },
   "parameters": {
@@ -26,7 +26,7 @@
   "resources": [
     {
       "type": "Microsoft.Kusto/clusters",
-      "apiVersion": "2021-08-27",
+      "apiVersion": "2023-08-15",
       "name": "[parameters('name')]",
       "location": "[parameters('location')]",
       "sku": {
@@ -38,6 +38,9 @@
       },
       "properties": {
         "enableDiskEncryption": true
+      },
+      "metadata": {
+        "description": "An example data explorer cluster using a managed identity."
       }
     }
   ]

docs/examples-signalr.bicep

@@ -9,8 +9,8 @@ param name string
 @description('The location resources will be deployed.')
 param location string = resourceGroup().location
 
-// An example SignalR Service
-resource service 'Microsoft.SignalRService/signalR@2021-10-01' = {
+@description('A Standard tier SignalR Service with key based auth disabled.')
+resource service 'Microsoft.SignalRService/signalR@2023-02-01' = {
   name: name
   location: location
   kind: 'SignalR'