Refactor documentation across multiple sections for clarity and consistency, including GitHub Actions, PowerShell Modules, Function Apps, DSC, and Scripts.

Author: MariusStorhaug

docs/GitHub-Actions/index.md

@@ -1,34 +1,18 @@
 # GitHub Actions
 
-PSModule provides a set of reusable GitHub Actions built with the [PSModule framework](https://github.com/PSModule/PSModule) and published to the [GitHub Marketplace](https://github.com/marketplace?&verification=&query=publisher%3Apsmodule).
+## What it is
 
-## Getting started
+GitHub Actions is a CI/CD and workflow automation platform built into GitHub. Actions are reusable steps that compose into pipelines triggered by repository events — pushes, pull requests, issue comments, schedules, and more. PSModule's actions are composite actions written in PowerShell and published to the [GitHub Marketplace](https://github.com/marketplace?&verification=&query=publisher%3Apsmodule). See the [official GitHub Actions documentation](https://docs.github.com/en/actions).
 
-<details>
-   <summary>About</summary>
+## Why we care
 
-A composite action is a reusable action that is made up of one or more steps. Composite actions can be used to encapsulate common tasks or workflows that can be reused across multiple repositories. They are a great way to share code and best practices with the community, and they can help to streamline the development process by providing a consistent way to perform common tasks.
-We have created a framework that automates the process of creating, testing, and publishing PowerShell based GitHub Actions to the GitHub Marketplace. This framework is designed to make it easy for developers to create and share their GitHub Actions with the community.
+Reusable actions are the foundation of a scalable, consistent DevOps practice on GitHub. Encapsulating common tasks — building, testing, releasing, and deploying PowerShell artifacts — into shared, versioned actions eliminates duplication and enforces best practices automatically across every repository in the organization. A single improvement to a shared action benefits all consumers immediately.
 
-</details>
+## How we do it
 
-<details>
-   <summary>How we do it in PSModule</summary>
+PSModule actions are built from the [Template-Action](https://github.com/PSModule/Template-Action) repository template, which sets up automated workflows for testing and publishing to the GitHub Marketplace. Each action is a composite action backed by PowerShell logic, following consistent input/output conventions. PR labels control versioning, and the `RepoType: Action` custom property integrates each repository with organization-wide tooling.
 
-Projects based on the `Template-Action` repository template will automatically have the necessary workflows and configurations set up to automate the process of creating, testing, and deploying PowerShell based GitHub Actions. This includes workflows for building, testing, and deploying the action, as well as a configuration file for setting up the action's metadata and dependencies.
-Using custom properties we set `RepoType` to `Action`.
-We use branch policies to control the flow of changes to the `main` branch, and we use labels to control the versioning of the action when a pull request is merged.
-
-</details>
-
-<details>
-   <summary>Create a new project</summary>
-
-1. Create a repository based on the template [Template-Action](https://github.com/PSModule/Template-Action).
-
-</details>
-
-## GitHub Actions on the GitHub Marketplace
+## What we have delivered
 
 <!-- ACTION_LIST_START -->
 

docs/PowerShell/DSC/index.md

@@ -1,5 +1,17 @@
-# DSC
+# PowerShell Desired State Configuration
 
-PowerShell Desired State Configuration (DSC) resources for declarative system configuration.
+## What it is
 
-> This section is coming soon. Standards and conventions for DSC resources will be documented here.
+PowerShell Desired State Configuration (DSC) is a declarative management platform built into PowerShell that defines what a system should look like and enforces that state continuously. Administrators describe the desired configuration of a node using DSC resources; the DSC engine ensures the system converges to and stays in that state. See the [official DSC documentation](https://learn.microsoft.com/en-us/powershell/dsc/overview).
+
+## Why we care
+
+DSC applies the same repeatability and version-control discipline to infrastructure that code gets from source control. In a DevOps context, declarative configuration means system state is auditable, drift is detectable, and environment provisioning becomes reproducible — closing the gap between application deployment and infrastructure management without resorting to imperative scripts.
+
+## How we do it
+
+> Standards and conventions for DSC resources within the PSModule framework are coming soon.
+
+## What we have delivered
+
+> No DSC resource repositories have been published yet.

docs/PowerShell/FunctionApps/index.md

@@ -1,47 +1,18 @@
-# Function Apps
+# PowerShell-based Function Apps
 
-PSModule Function Apps are PowerShell based Azure Functions that run serverless, event-driven code. They are built with the [PSModule framework](https://github.com/PSModule/PSModule) and follow a consistent layout, naming, and versioning convention.
+## What it is
 
-## Getting started
+Azure Function Apps are a serverless compute service that runs event-driven code without requiring dedicated infrastructure. PSModule function apps are written in PowerShell and deployed to Azure, responding to events such as HTTP requests, timers, or Azure service messages. See the [Azure Functions documentation](https://learn.microsoft.com/en-us/azure/azure-functions/functions-overview).
 
-<details>
-   <summary>About</summary>
+## Why we care
 
-A PowerShell based Azure Function App is a serverless compute service that enables you to run event-driven code without having to manage the infrastructure. Azure Functions are ideal for processing data, integrating systems, and building simple APIs or microservices. They can be triggered by a variety of events, such as HTTP requests, timers, or messages from Azure services like Azure Storage, Event Grid, or Service Bus.
-We have created a framework that automates the process of creating, testing, and deploying PowerShell based Azure Function Apps to Azure. This framework is designed to make it easy for developers to create and deploy their Azure Function Apps without having to worry about the underlying infrastructure.
+Serverless PowerShell functions extend automation into cloud-native, event-driven scenarios that traditional scripts and pipelines cannot cover alone. They enable lightweight, always-on integrations — such as GitHub App webhooks, scheduled maintenance tasks, and API bridges — to run reliably without managing servers or paying for idle compute.
 
-</details>
+## How we do it
 
-<details>
-   <summary>How we do it in PSModule</summary>
+PSModule function apps are built from the [Template-FunctionApp](https://github.com/PSModule/Template-FunctionApp) repository template, which wires up the [Process-FunctionApp](https://github.com/PSModule/Process-FunctionApp) reusable workflow for automated build, test, and Azure deployment. The `AZURE_CREDENTIALS` secret provides the service principal for deployment, and PR labels control versioning the same way they do for modules. The `RepoType: FunctionApp` custom property integrates each repository with organization-wide tooling.
 
-Projects based on the `Template-FunctionApp` repository template will automatically have the necessary workflows and configurations set up to automate the process of creating, testing, and deploying PowerShell based Azure Function Apps to Azure. This includes workflows for building, testing, and deploying the function app, as well as a configuration file for setting up the function app's metadata and dependencies.
-Using custom properties we set `RepoType` to `FunctionApp`.
-We use branch policies to control the flow of changes to the `main` branch, and we use labels to control the versioning of the module when a pull request is merged.
-
-</details>
-
-<details>
-   <summary>Create a new project</summary>
-
-1. Create a repository based on the template [Template-FunctionApp](https://github.com/PSModule/Template-FunctionApp). The module will by default use the name of the repository.
-1. Create a repository or organization secret called `AZURE_CREDENTIALS`, holding the credentials for the Azure service principal.
-1. Configure the settings you want for the repository including a branch policy for the `main` branch.
-1. On a topic branch:
-   1. develop the code you want to add to your function app.
-   1. delete the parts you do not need.
-   1. update the tests in the `tests` folder.
-1. Create a PR. Add a label to the PR depending on what you want to do.
-    - `Major` - Will create a major release (vX.0.0) when merged. If specified with "Prerelease", a major version will be created using the prerelease tag (vX.0.0-\<branchName\>).
-    - `Minor` - Will create a minor release (vX.Y.0) when merged. If specified with "Prerelease", a minor version will be created using the prerelease tag (vX.Y.0-\<branchName\>).
-    - `Patch` - Will create a minor release (vX.Y.Z) when merged. If specified with "Prerelease", a minor version will be created using the prerelease tag (vX.Y.Z-\<branchName\>). A patch version bump is the default if nothing is specified for the PR.
-    - `Prerelease` - CI will create a prerelease of the module using the branch name as a prerelease tag in the version. This will create both a repository release and a prerelease version of the module on the PowerShell Gallery.
-1. Once the PR is created, the [Process-FunctionApp](https://github.com/PSModule/Process-FunctionApp) workflow will trigger.
-1. When the PR is merged, a release will be created and the function app will be deployed to Azure with a stable version based on the version bump indicator the PR was was labeled with. Prerelease tags will be cleaned up on the repository.
-
-</details>
-
-## Function Apps we maintain
+## What we have delivered
 
 <!-- FUNCTIONAPP_LIST_START -->
 

docs/PowerShell/Modules/index.md

@@ -1,53 +1,22 @@
-# Modules
+# PowerShell Modules
 
-PSModule modules are reusable PowerShell libraries published to the PowerShell Gallery. They are built with the [PSModule framework](https://github.com/PSModule/PSModule) and follow a consistent layout, naming, and versioning convention.
+## What it is
 
-## What's covered
+A PowerShell module is a distributable package of functions, cmdlets, and scripts built to be shared and reused across environments. Modules are published to and installed from the [PowerShell Gallery](https://www.powershellgallery.com/), the official repository for PowerShell packages. See the [official PowerShell modules documentation](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_modules).
 
-- **[Standards](Standards.md)** — Repository layout, naming, style, parameter design, comment-based help, and SOLID applied to PowerShell modules.
-- **[Test Specification](Test-Specification.md)** — How we write Pester tests: structure, hierarchy, and naming conventions.
-- **[Versioning](Versioning.md)** — How changes to the public interface determine the SemVer version bump.
-
-## Getting started
-
-<details>
-   <summary>About</summary>
-
-A PowerShell module is a set of functions, scripts, and cmdlets that are bundled together in a single package. Modules are used to organize and distribute code in a way that is easy to use and share. They can be used to extend the functionality of PowerShell, automate tasks, and create reusable code that can be shared with others.
-We have created a framework that automates the process of creating, testing, and publishing PowerShell modules to the PowerShell Gallery. This framework is designed to make it easy for developers to create and share their PowerShell modules with the community.
+## Why we care
 
-</details>
+Modules are the primary unit of reusable automation in the PowerShell ecosystem. Packaging logic into versioned, tested, and published modules keeps pipelines maintainable and composable — any team or workflow can consume shared functions without copying code. Strong module conventions make the public API surface explicit, so breaking changes are intentional and versioned correctly through SemVer.
 
-<details>
-   <summary>How we do it in PSModule</summary>
+## How we do it
 
-Projects based on the `Template-PSModule` repository template will automatically have the necessary workflows and configurations set up to automate the process of creating, testing, and publishing PowerShell modules to the PowerShell Gallery. This includes workflows for building, testing, and releasing the module, as well as a configuration file for setting up the module's metadata and dependencies.
-Using custom properties we set `RepoType` to `Module`.
-We use branch policies to control the flow of changes to the `main` branch, and we use labels to control the versioning of the module when a pull request is merged.
+PSModule provides a standardized framework based on the [Template-PSModule](https://github.com/new?template_name=Template-PSModule&template_owner=PSModule) repository template. All modules follow a consistent directory layout, naming convention, and coding style. The [Process-PSModule](https://github.com/PSModule/Process-PSModule) reusable workflow automates building, testing, and publishing to the PowerShell Gallery. Version increments are driven by PR labels (`Major`, `Minor`, `Patch`, `Prerelease`), and the `RepoType: Module` custom property integrates each repository with organization-wide tooling.
 
-</details>
-
-<details>
-   <summary>Create a new project</summary>
-
-1. [Create a repository based on the template Template-PSModule](https://github.com/new?template_name=Template-PSModule&template_owner=PSModule). The module will by default use the name of the repository. See [Process-PSModule](https://github.com/PSModule/Process-PSModule) for more info on choosing another name than the repository name.
-1. Create a repository or organization secret called `APIKEY` holding the API key for the PowerShell Gallery.
-1. Configure the settings you want for the repository including a branch policy for the `main` branch.
-1. On a topic branch:
-   1. develop the code you want to add to your module.
-   1. delete the parts you do not need.
-   1. update the tests in the `tests` folder.
-1. Create a PR. Add a label to the PR depending on what you want to do.
-   - `Major` - Will create a major release (vX.0.0) when merged. If specified with "Prerelease", a major version will be created using the prerelease tag (vX.0.0-\<branchName\>).
-   - `Minor` - Will create a minor release (vX.Y.0) when merged. If specified with "Prerelease", a minor version will be created using the prerelease tag (vX.Y.0-\<branchName\>).
-   - `Patch` - Will create a minor release (vX.Y.Z) when merged. If specified with "Prerelease", a minor version will be created using the prerelease tag (vX.Y.Z-\<branchName\>). A patch version bump is the default if nothing is specified for the PR.
-   - `Prerelease` - CI will create a prerelease of the module using the branch name as a prerelease tag in the version. This will create both a repository release and a prerelease version of the module on the PowerShell Gallery.
-1. Once the PR is created, the [Process-PSModule](https://github.com/PSModule/Process-PSModule) workflow will trigger.
-1. When the PR is merged, a release will be created and the module will be published to the PowerShell Gallery with a stable version based on the version bump indicator the PR was was labeled with. Prerelease tags will be cleaned up on the repository.
-
-</details>
+- **[Standards](Standards.md)** — Repository layout, naming, style, parameter design, comment-based help, and SOLID applied to PowerShell modules.
+- **[Test Specification](Test-Specification.md)** — How we write Pester tests: structure, hierarchy, and naming conventions.
+- **[Versioning](Versioning.md)** — How changes to the public interface determine the SemVer version bump.
 
-## Modules on the PowerShell Gallery
+## What we have delivered
 
 <!-- MODULE_LIST_START -->
 

docs/PowerShell/Scripts/index.md

@@ -1,7 +1,19 @@
-# Scripts
+# PowerShell Scripts
 
-Standalone PowerShell scripts used for automation, tooling, and developer workflows across the PSModule ecosystem.
+## What it is
 
-## What's covered
+A PowerShell script is a standalone `.ps1` file that executes a sequence of commands to accomplish a task. Unlike modules, scripts are not packaged for distribution — they run directly in a shell, pipeline, or CI/CD runner. See the [official PowerShell scripting documentation](https://learn.microsoft.com/en-us/powershell/scripting/overview).
+
+## Why we care
+
+Scripts are the fastest path from intent to automation. In GitHub Actions and DevOps pipelines, scripts orchestrate deployment steps, invoke APIs, transform data, and bridge gaps between purpose-built tools. Consistent, well-structured scripts are easier to review, test, and debug — reducing the risk of pipeline failures and onboarding friction for new contributors.
+
+## How we do it
+
+PSModule scripts follow a set of conventions covering naming, parameter design, error handling, and output format. These standards ensure scripts behave predictably in both pipeline and interactive contexts.
 
 - **[Standards](Standards.md)** — How we write, name, and structure PowerShell scripts.
+
+## What we have delivered
+
+> No standalone script repositories are maintained yet. Scripts are typically co-located with the module or workflow that uses them.

docs/PowerShell/index.md

@@ -1,9 +1,10 @@
 # PowerShell
 
-PowerShell is the primary language of the PSModule ecosystem. This section covers how we write, test, version, and distribute PowerShell code — across modules, scripts, and DSC resources.
+PowerShell is the primary language of the PSModule ecosystem. This section covers how we write, test, version, and distribute PowerShell code across all artifact types.
 
 ## What's covered
 
 - **[Modules](Modules/index.md)** — Reusable libraries published to the PowerShell Gallery. Standards, test specification, and versioning.
 - **[Scripts](Scripts/index.md)** — Standalone automation scripts. Standards for how we write and structure them.
-- **[DSC](DSC/index.md)** — Desired State Configuration resources. Coming soon.
+- **[Function Apps](FunctionApps/index.md)** — Serverless Azure Functions written in PowerShell.
+- **[Desired State Configuration](DSC/index.md)** — Declarative system configuration resources.