FIXUP: PR review fixes #3: final documentation tweaks.

website/content/api-docs/secret/transform.mdx

@@ -469,8 +469,8 @@ template exists, it will be updated with the new attributes.
   encoding and decoding operations.
 
 -	`encode_format` `(string)` -
-  The regular expression template to use to format encoded values. For example,
-  this can be used to normalize the encoded output. This is only used during FPE
+  The regular expression template to use to format encoded values. This can be
+  used to normalize the encoded output. This is only used during FPE
   transformations.
 
 - `decode_formats` `(key-value-map: {})` -
@@ -814,7 +814,7 @@ operation.
   The password value to use when connecting to the database.
 
 - `transformation_type`: `(string: "tokenization")` -
-  The transformation type. Currently only tokenization is supported.
+  The transformation type. Currently only `tokenization` is supported.
 
 ### Sample Payload
 
@@ -955,9 +955,10 @@ This endpoint encodes the provided value using a named role.
   7-byte value that is then base64 encoded.
 
 - `reference` `(string: "")` -
-  Only valid on batch requests using 'batch_input' below.  A user-supplied
-  string that will be present on the corresponding item in the batch
-  response, to assist in correlating inputs with outputs.
+  A user-supplied string that will be present in the `reference` field on the
+  corresponding `batch_results` item in the response, to assist in understanding
+  which result corresponds to a particular input. Only valid on batch requests
+  when using ‘batch_input’ below.
 
 - `batch_input` `(array<object>: nil)` -
   Specifies a list of items to be encoded in a single batch. When this
@@ -1082,8 +1083,11 @@ This endpoint decodes the provided value using a named role.
   Specifies the value to be decoded.
 
 - `decode_format` `(string)` -
-  The name of the decode format to use for decoding. If one is not specified,
-  the template's pattern will be used. Only applicable for FPE transformations.
+  The name of the decode format to use for decoding. These are defined in
+  `decode_formats` when creating the transformation's template, and can be used
+  to selectively decode or format the output. If one is not defined or
+  specified, the template's pattern will be used. Only applicable for FPE
+  transformations.
 
 - `transformation` `(string)` –
   Specifies the transformation within the role that should be used for this
@@ -1096,9 +1100,10 @@ This endpoint decodes the provided value using a named role.
   source. The tweak must be a 7-byte value that is then base64 encoded.
 
 - `reference` `(string: "")` -
-  Only valid on batch requests using 'batch_input' below.  A user-supplied
-  string that will be present on the corresponding item in the batch
-  response, to assist in correlating inputs with outputs.
+  A user-supplied string that will be present in the `reference` field on the
+  corresponding `batch_results` item in the response, to assist in understanding
+  which result corresponds to a particular input. Only valid on batch requests
+  when using ‘batch_input’ below.
 
 - `batch_input` `(array<object>: nil)` -
   Specifies a list of items to be decoded in a single batch. When this
@@ -1244,9 +1249,10 @@ Only valid for tokenization transformations.
   must be specified.
 
 - `reference` `(string: "")` -
-  Only valid on batch requests using 'batch_input' below.  A user-supplied
-  string that will be present on the corresponding item in the batch
-  response, to assist in correlating inputs with outputs.
+  A user-supplied string that will be present in the `reference` field on the
+  corresponding `batch_results` item in the response, to assist in understanding
+  which result corresponds to a particular input. Only valid on batch requests
+  when using ‘batch_input’ below.
 
 - `batch_input` `(array<object>: nil)` -
   Specifies a list of items to be validated in a single batch. When this
@@ -1319,9 +1325,10 @@ transformations.
   must be specified.
 
 - `reference` `(string: "")` -
-  Only valid on batch requests using 'batch_input' below.  A user-supplied
-  string that will be present on the corresponding item in the batch
-  response, to assist in correlating inputs with outputs.
+  A user-supplied string that will be present in the `reference` field on the
+  corresponding `batch_results` item in the response, to assist in understanding
+  which result corresponds to a particular input. Only valid on batch requests
+  when using ‘batch_input’ below.
 
 - `batch_input` `(array<object>: nil)` -
   Specifies a list of items to be decoded in a single batch. When this
@@ -1393,9 +1400,10 @@ Only valid for tokenization transformations.
   must be specified.
 
 - `reference` `(string: "")` -
-  Only valid on batch requests using 'batch_input' below.  A user-supplied
-  string that will be present on the corresponding item in the batch
-  response, to assist in correlating inputs with outputs.
+  A user-supplied string that will be present in the `reference` field on the
+  corresponding `batch_results` item in the response, to assist in understanding
+  which result corresponds to a particular input. Only valid on batch requests
+  when using ‘batch_input’ below.
 
 - `batch_input` `(array<object>: nil)` -
   Specifies a list of items to be decoded in a single batch. When this

website/content/docs/secrets/transform/index.mdx

@@ -120,7 +120,7 @@ values.
    A transformation must be provided if the role contains more than one
    transformation. A tweak must be provided if the tweak source for the
    transformation is "supplied" or "generated". A decode format can optionally
-   be provided, if none is provided, the decoded output will be formatted to
+   be provided. If one isn't provided, the decoded output will be formatted to
    match the template's pattern as in the previous example.
 
 ## Roles, Transformations, Templates, and Alphabets