Acrolinx and rebase

Author: sdwheeler

dsc/docs-conceptual/dsc-3.0/concepts/configurations.md

@@ -1,7 +1,7 @@
 ---
 description: >-
   DSC configuration documents are YAML or JSON data files that define the desired state of a system
-  declaratively. They are used to retrieve, validate, and enforce the state of multiple resource
+  declaratively. They're used to retrieve, validate, and enforce the state of multiple resource
   instances.
 ms.date: 03/04/2025
 title: DSC configuration documents
@@ -28,7 +28,7 @@ Configuration documents are YAML or JSON files that contain a single object. The
 properties define how DSC processes the document. The top-level properties for a document are:
 
 - `$schema` (required) - Defines the URI for the JSON Schema the document adheres to. DSC
-  uses this to know how to validate and interpret the document.
+  uses the schema to validate and interpret the document.
 - `resources` (required) - Defines the collection of resource instances the document manages.
 - `metadata` (optional) - Defines an arbitrary set of annotations for the document. The annotations
   can include notes like who authored the document, the last time someone updated it, or any other
@@ -37,11 +37,11 @@ properties define how DSC processes the document. The top-level properties for a
 
   DSC applies validation to the `Microsoft.DSC` property. For more information, see the
   [DSC Configuration document metadata schema][02] reference.
-- `parameters` (optional) - Defines a set of runtime options for the configuration. Parameters can
-  be referenced by resource instances to reduce duplicate definitions or enable dynamic values.
+- `parameters` (optional) - Defines a set of runtime options for the configuration. Resource
+  instances can reference parameters to reduce duplicate definitions or enable dynamic values.
   Parameters can have default values and can be set on any configuration operation.
-- `variables` (optional) - Defines a set of reusable values for the configuration. Variables can be
-  referenced by resource instances to reduce duplicate definitions.
+- `variables` (optional) - Defines a set of reusable values for the configuration. Resource
+  instances can reference variables to reduce duplicate definitions.
 
 ## Defining a configuration document
 
@@ -100,9 +100,9 @@ incompatible state for the instance on every run.
 ## Getting the current state of a configuration
 
 The `dsc config get` command retrieves the current state of the resource instances defined in a
-configuration document. DSC also collects any message emitted by the resources during the
-operation, indicates whether any of the resources raised an error, and provides metadata about the
-operation as a whole and for each resource instance.
+configuration document. For each resource instance, DSC collects messages emitted by the resources
+during the operation, indicates whether any of the resources raised an error, and provides metadata
+about the operation as a whole.
 
 ```sh
 dsc config get --file ./example.config.dsc.yaml
@@ -137,14 +137,14 @@ hadErrors: false
 The `dsc config test` command compares the current state of the resource instances to their desired
 state. The result for each instance includes:
 
-- The desired state for the instance.
-- The actual state of the instance.
-- Whether the instance is in the desired state.
-- The list of properties that are out of the desired state, if any.
+- The desired state for the instance
+- The actual state of the instance
+- Whether the instance is in the desired state
+- The list of properties that are out of the desired state, if any
 
-DSC also collects any message emitted by the resources during the operation, indicates whether any
-of the resources raised an error, and provides metadata about the operation as a whole and for each
-resource instance.
+For each resource instance, DSC also collects messages emitted by the resources during the
+operation, indicates whether any of the resources raised an error, and provides metadata about the
+operation as a whole.
 
 ```sh
 dsc config test --file /example.config.dsc.yaml
@@ -193,9 +193,9 @@ their desired state. The result for each instance includes:
 - The state of the instance after the operation.
 - Which properties the operation changed, if any.
 
-DSC also collects any message emitted by the resources during the operation, indicates whether any
-of the resources raised an error, and provides metadata about the operation as a whole and for each
-resource instance.
+For each resource instance, DSC also collects messages emitted by the resources during the
+operation, indicates whether any of the resources raised an error, and provides metadata about the
+operation as a whole.
 
 ```sh
 dsc config set --file ./example.config.dsc.yaml
@@ -240,6 +240,7 @@ hadErrors: false
 - [DSC Configuration document schema reference][05]
 - [Command line reference for the 'dsc config' command][06]
 
+<!-- link references -->
 [01]: ./resources.md
 [02]: ../reference/schemas/config/metadata.md#microsoftdsc
 [03]: ../reference/schemas/config/document.md

dsc/docs-conceptual/dsc-3.0/concepts/enhanced-authoring.md

@@ -10,14 +10,14 @@ title:   Authoring with enhanced schemas
 # Authoring with enhanced schemas
 
 Working with Microsoft's Desired State Configuration (DSC) platform involves writing DSC
-[configuration documents][01] and [resource manifests][02]. Configuration documents are YAML or
-JSON data files that declare the desired state of a system. Resource manifests are JSON or YAML
-data files that define a DSC command resource.
+[configuration documents][01] and [resource manifests][02]. Configuration documents are YAML or JSON
+data files that declare the desired state of a system. Resource manifests are JSON or YAML data
+files that define a DSC command resource.
 
 DSC validates these data files with a JSON schema. While the schemas DSC uses for validation are
-useful for authoring configuration documents and resource manifests, Microsoft also defines a set
-of enhanced schemas for authoring the files in VS Code. These schemas define extra keywords
-specific to VS Code that:
+useful for authoring configuration documents and resource manifests, Microsoft also defines a set of
+enhanced schemas for authoring the files in VS Code. These schemas define extra keywords specific to
+VS Code that:
 
 - Improve the contextual help when hovering on or selecting a property in the data file.
 - Add contextual help for enum values.
@@ -30,14 +30,14 @@ specific to VS Code that:
 >
 > These schemas are only for improving the authoring experience. If you try to validate the
 > configuration document or resource manifest with a tool that doesn't support the extended
-> vocabulary, the tool may raise an error.
+> vocabulary, the tool might raise an error.
 >
 > The enhanced schemas share the same source definition as the canonical schemas and validate the
 > data in the same way. However, they include non-canonical keywords. For maximum compatibility
 > with other tools, the canonical schemas only use the core JSON schema vocabularies.
 
-For the full list of recognized and supported schema URIs, including the enhanced authoring
-schemas, see the `$schema` sections in [DSC Configuration document schema reference][03] and
+For the full list of recognized and supported schema URIs, including the enhanced authoring schemas,
+see the `$schema` sections in [DSC Configuration document schema reference][03] and
 [DSC resource manifest schema reference][04].
 
 ## Enhanced schema examples
@@ -61,7 +61,7 @@ When possible, the hover help includes a link to the online documentation.
 :::image-end:::
 <!-- markdownlint-enable MD013 -->
 
-When using IntelliSense while authoring with an enhanced schema, the quick info shown for the
+When you use IntelliSense while authoring with an enhanced schema, the quick info shown for the
 completion options displays as rendered Markdown. When possible, the quick info includes a link to
 the online documentation.
 
@@ -97,19 +97,19 @@ snippets in VS Code.
 
 <!-- markdownlint-disable MD013 -->
 :::image type="complex" source="media/enhanced-authoring/error-messages.png" alt-text="This screenshot shows an enhanced error message for failed validation.":::
-   This screenshot shows a contextual error message when the name property for a resource instance doesn't match the validating regular expression. The value is the string 'invalid?' and the error message says "Invalid value for instance name. An instance name must be a non-empty string containing only letters, numbers, and spaces."
+   This screenshot shows a contextual error message when the name property for a resource instance doesn't match the validating regular expression. The value is the string 'invalid?' and the error message says "Invalid value for instance name. An instance name must be a nonempty string containing only letters, numbers, and spaces."
 :::image-end:::
 <!-- markdownlint-enable MD013 -->
 
-When defining values, the enhanced schemas have contextual error messages instead of the default
-error messages that JSON schema validation raises. This is particularly helpful for properties that
-must match a regular expression, where the default message just indicates that the value is invalid
-and lists the regular expression pattern.
+When you define values, the enhanced schemas have contextual error messages instead of the default
+error messages that JSON schema validation raises. These values are helpful for properties that must
+match a regular expression, where the default message just indicates that the value is invalid and
+lists the regular expression pattern.
 
 ## Using the enhanced configuration document schema
 
 To associate every configuration document with the enhanced schema, add the following snippet to
-your [settings.json] file in VS Code. You can define these options in your user settings or for a
+your `settings.json` file in VS Code. You can define these options in your user settings or for a
 specific workspace.
 
 <!-- markdownlint-disable MD013 -->
@@ -154,9 +154,9 @@ when authoring configuration documents in JSON, you must define the schema assoc
 
 ## Using the enhanced resource manifest schema
 
-To use the enhanced schema when authoring resource manifests, add the following snippet to
-your [settings.json] file in VS Code. You can define this option in your user settings or for a
-specific workspace.
+To use the enhanced schema when authoring resource manifests, add the following snippet to your
+`settings.json` file in VS Code. You can define this option in your user settings or for a specific
+workspace.
 
 <!-- markdownlint-disable MD013 -->
 ```json

dsc/docs-conceptual/dsc-3.0/concepts/resources.md

@@ -26,7 +26,7 @@ DSC supports several kinds of resources:
 - A resource defined with a resource manifest is a _command_ resource. DSC uses the manifest
   to determine how to invoke the resource and how to validate the resource instance properties.
 - A _group resource_ is a command resource with a `resources` property that takes an array of
-  resource instances and processes them. Group resources may apply special handling to their nested
+  resource instances and processes them. Group resources can apply special handling to their nested
   resource instances, like changing the user the resources run as.
 - An _adapter resource_ is a group resource that enables the use of non-command resources with DSC.
   For example, the `Microsoft.DSC/PowerShell` and `Microsoft.Windows/WIndowsPowerShell` adapter
@@ -35,7 +35,7 @@ DSC supports several kinds of resources:
 
 ## Resource type names
 
-Resources are identified by their fully qualified type name. The type name is used to specify a
+You identify resources by their fully qualified type name. The type name is used to specify a
 resource in configuration documents and as the value of the `--resource` flag when using the
 `dsc resource *` commands.
 
@@ -50,7 +50,7 @@ organizing resources into related namespaces, like `Microsoft.SqlServer/Database
 `Microsoft.SqlServer.Database/Role`.
 
 For more information about type names and how DSC validates them, see
-[DSC Resource fully qualified type name schema reference][01].
+[DSC Resource fully qualified type name schema reference][03].
 
 ## Resource properties
 
@@ -60,7 +60,7 @@ instance schema.
 
 Properties are optional by default. Resources can be invoked directly or declared in a
 configuration with only the properties that are relevant to the current task or purpose. You don't
-need to declare every property for an instance. Properties may have default values for their
+need to declare every property for an instance. Properties can have default values for their
 desired state.
 
 Most properties are one of the basic types:
@@ -77,10 +77,10 @@ subproperties can be basic or complex, but they're usually a basic type.
 
 Resources can define their properties as read-only or write-only:
 
-- A _read-only resource property_ defines metadata about an instance that the resource can retrieve
-  but that a user can't directly set. You can't specify read-only properties in the desired state
-  for an instance. Examples of read-only properties include the last time a file was modified or
-  the author of an installed software package.
+- A _read-only resource property_ contains metadata that the resource can retrieve but that a user
+  can't directly set. You can't specify read-only properties in the desired state for an instance.
+  Examples of read-only properties include the last time a file was modified or the author of an
+  installed software package.
 - A _write-only resource property_ defines a value that the resource uses during a resource
   operation that can't be returned for the current state of an instance. Examples of
   write-only properties include credentials used to authenticate during a resource operation and
@@ -92,7 +92,7 @@ canonical property in its instance schema indicates that the resource manages in
 created and deleted. If a resource has the `_exist` canonical property and the `delete` capability,
 DSC can invoke the **Delete** operation instead of **Set** when the desired state
 indicates the instance shouldn't exist. For more information about the available canonical
-properties, see [DSC canonical properties](../reference/schemas/resource/properties/overview.md).
+properties, see [DSC canonical properties][04].
 
 ## Listing resources
 
@@ -163,12 +163,12 @@ strict case-insensitive comparison of the desired and actual values for the inst
 Only resources that have advanced or complex validation requirements need to implement the **Test**
 operation themselves.
 
-Use the `dsc resource test` command to invoke the operation. DSC returns data that includes:
+Use the `dsc resource test` command to invoke the operation. DSC returns the following data:
 
-- The desired state for the instance.
-- The actual state of the instance.
-- Whether the instance is in the desired state.
-- The list of properties that aren't in the desired state.
+- The desired state for the instance
+- The actual state of the instance
+- Whether the instance is in the desired state
+- The list of properties that aren't in the desired state
 
 For example, you can test whether a specific registry key exists:
 
@@ -241,8 +241,8 @@ changedProperties:
 
 ### Delete operations
 
-Some resources implement the **Delete** operation for convenience. This enables you to invoke the
-resource to remove an instance from the system.
+Some resources implement the **Delete** operation for convenience. This operation enables you to
+invoke the resource to remove an instance from the system.
 
 Use the `dsc resource delete` command to invoke the operation. When you invoke the **Delete**
 operation, DSC returns no output unless there's an error.
@@ -258,7 +258,7 @@ dsc resource delete --resource Microsoft.Windows/Registry --input '{
 ### Export operations
 
 Some resources implement the **Export** operation, which returns every instance of the resource on
-the system. This can help you discover how a machine is currently configured.
+the system. This operation can help you discover how a machine is currently configured.
 
 Use the `dsc resource export` command to invoke the operation. When you invoke the **Export**
 operation, DSC returns an array of resources instance definitions you can copy into a configuration
@@ -273,9 +273,9 @@ dsc resource export --resource Microsoft.DSC/Process
 ## Declaring resource instances
 
 DSC configuration documents enable managing more than one resource or resource instance at a time.
-Configuration documents declare a collection of resource instances and their desired state. This
-makes it possible to model complex desired states by composing different resources and instances
-together, like defining a security baseline for compliance or the settings for a web farm.
+Configuration documents declare a collection of resource instances and their desired state.
+Collections make it possible to model complex desired states by composing different resources and
+instances together, like defining a security baseline for compliance or the settings for a web farm.
 
 A resource instance declaration always includes:
 
@@ -303,13 +303,15 @@ resources:
 
 ## See also
 
-- [Anatomy of a DSC command resource][03] to learn about authoring resources in your language
+- [Anatomy of a DSC command resource][05] to learn about authoring resources in your language
   of choice.
-- [Configuration Documents][04] to learn about using resources in a configuration document.
-- [Command line reference for the 'dsc resource' command][05]
+- [Configuration Documents][06] to learn about using resources in a configuration document.
+- [Command line reference for the 'dsc resource' command][01]
 
-[01]: ../reference/schemas/definitions/resourceType.md
+<!-- link references -->
+[01]: ../reference/cli/resource/command.md
 [02]: ../reference/cli/resource/list.md
-[03]: ../resources/concepts/anatomy.md
-[04]: configurations.md
-[05]: ../reference/cli/resource/command.md
+[03]: ../reference/schemas/definitions/resourceType.md
+[04]: ../reference/schemas/resource/properties/overview.md
+[05]: ../resources/concepts/anatomy.md
+[06]: configurations.md