Merge pull request #122 from michaeltlombardi/docs/main/update-readme

(DOCS) Update readme for public alpha

README.md

@@ -1,17 +1,63 @@
 # DSCv3
 
-[NOTICE] This repo is currently NOT accepting contributions and is public and Open Source to show progress.  Once we are at a feature complete state, we can start taking contributions.
-
-## High level design goals
-
-- Cross-platform and Open Source
-- Bring your own agent
-  - No LCM support
-  - Azure Guest Config, Azure Automanaged VM, WinGet partners as orchestration agents
-- Author resources in PowerShell or any language
-  - Need to be executable from command-line
-  - Still supporting script based and class based resources
-- Native `dsc` command removes dependency on PowerShell
-  - Able to invoke PowerShell based resources (Windows PowerShell or PowerShell 7 runtimes)
-- Move from MOF to JSON
-- End users can author configuration in YAML or JSON and apply them using `dsc` command
+> [!NOTE]
+> This repo isn't accepting code contributions. It's public and open source to show progress and
+> enable feedback. Once we're at a feature complete state, we can start taking code contributions.
+
+## What's DSCv3?
+
+DSCv3 is the latest iteration of Microsoft's Desired State Configuration platform. DSCv3 is an open
+source command line application that abstracts the management of software components declaratively
+and idempotently. DSCv3 runs on Linux, macOS, and Windows without any external dependencies.
+
+With DSCv3, you can:
+
+- Author resources to manage your systems in any language
+- Invoke individual resources
+- Create configuration documents that define the desired state of a system
+
+### Differences from PowerShell DSC
+
+DSCv3 differs from PowerShell DSC in a few important ways:
+
+- DSCv3 doesn't depend on PowerShell. You can use DSCv3 without PowerShell installed and manage
+  resources written in bash, python, C#, Go, or any other language.
+- DSCv3 doesn't include a local configuration manager. DSCv3 is invoked as a command. It doesn't
+  run as a service.
+- Non-PowerShell resources define their schemas with JSON files, not MOF files.
+- Configuration documents are defined in JSON or YAML files, not PowerShell script files.
+
+Importantly, while DSCv3 represents a major change to the DSC platform, DSCv3 is able to invoke
+PowerShell DSC Resources, including script-based and class-based DSC Resources, as they exist today. The
+configuration documents aren't compatible, but all published PowerShell DSC Resources are. You can
+use PowerShell DSC resources in DSCv3 with both Windows PowerShell and PowerShell.
+
+## Installing DSCv3
+
+To install DSC v3:
+
+1. Download the [latest release from this repository][01].
+1. Expand the release archive.
+1. Add the folder containing the expanded archive contents to the `PATH`.
+
+## Expore DSCv3
+
+If you're new to DSC or configuration management, we recommend reviewing the [documentation][02].
+
+If you're already familiar with DSC or just want to start experimenting with v3, we recommend
+reviewing the [Samples repository][03] and the accompanying [tutorial site][04].
+
+## Integrating with DSCv3
+
+DSCv3 is a platform tool that abstracts the concerns for defining and invoking resources. Higher
+order tools, like Azure Machine Configuration, Azure Automanaged VM, and WinGet are early partners
+for DSCv3 as orchestration agents.
+
+DSCv3 uses JSON schemas to define the structure of resources, configuration documents, and the
+outputs that DSCv3 returns. These schemas make it easier to integrate DSCv3 with other tools,
+because they standardize and document how to interface with DSCv3.
+
+[01]: https://github.com/PowerShell/DSC/releases/latest
+[02]: https://learn.microsoft.com/powershell/dsc/overview?view=dsc-3.0&preserve-view=true
+[03]: https://github.com/PowerShell/DSC-Samples
+[04]: https://powershell.github.io/DSC-Samples