docs: updated words

docs/getting-started/test-a-validation.md

@@ -77,7 +77,7 @@ We'd like to verify that our rego policy is going to correctly evaluate the `pod
 
 ```json
 {
-    "podinfoDeployment": {}
+  "podinfoDeployment": {}
 }
 ```
 
@@ -114,27 +114,44 @@ tests:
 
 4. For the second test case, we want to verify that the policy is `not-satisfied` if the resource is found, but the number of replicas is 0. This mimics a scenario where the deployment is in the cluster, but there are no pods.
 
-To mimic the json manifest we expect for this scenario, we'd like to set the `podinfoDeployment.spec.replicas` to 0. We can do this by adding the following to the `changes` section:
+An abridged version of the json manifest we expect for this scenario is:
 
-```yaml
-- path: podinfoDeployment.status
-  type: update
-  value-map:
-    replicas: 0
+```json
+{
+  "podinfoDeployment": {
+    "apiVersion": "apps/v1",
+    "kind": "Deployment",
+    "metadata": {
+      "name": "podinfo"
+      // Rest of the metadata
+    },
+    "spec": {
+      "replicas": 0
+      // Rest of the spec
+    }
+  }
+}
 ```
 
-This is another test case where at first pass we'd expect to set up a change as follows:
+On first glance, we might be tempted to set the `podinfoDeployment.spec.replicas` to 0 using the following change:
 
 ```yaml
-# Does NOT work
+# invalid change for our resource!
 - path: podinfoDeployment.status.replicas
   type: update
   value: "0"
 ```
 
-However, this will not correctly generate the expected json structure, as the `replicas` field is a number, and not a string. Instead, we need to use the `value-map` change type, which allows us to set the value of a field to any type of value.
+However, this will NOT correctly generate the expected json structure since the `replicas` field is a number, and not a string. Instead, we need to use the `value-map` change type, which allows us to set the value of a field to any type of value, as follows:
+
+```yaml
+- path: podinfoDeployment.status
+  type: update
+  value-map:
+    replicas: 0
+```
 
-Now the tests will look like the following:
+Now the tests, containing both test cases, will become:
 
 ```yaml
 tests:

docs/reference/testing.md

@@ -107,7 +107,7 @@ Which will point to the labels key of the first namespace. Additionally, a `[-]`
 * In addition to simple selectors for a list, e.g., `path[key=value]`, complex filters can be used, e.g., `path[key=value,key2=value2]` or `path[key.subkey=value]`
 * Use double quotes to access keys that contain periods, e.g., `foo["some.key"=value]` or `foo["some.key/label"]`
 * To access the index of a list, use `[0]` (where 0 is any valid index) or `[-]` for the last item in the list
-* If you need to access a map key that is an integer, either use `foo["0"]` or `foo.0`
+* In the scenario where you need to access a map key which is a stringified integer (e.g., the "0" in `{ "foo": { "0": "some-value" }}`), either enclose the key in quotes, `foo["0"]`, or access through the normal path syntax, `foo.0`.
 
 ### Change Type Behavior