From 5f9d0d6e69fd52b838228a99ffaa8420ede63f9e Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 13:25:43 +0100 Subject: [PATCH 1/4] State glossary purpose and API definition directly --- docs/content/Dictionary/api.md | 4 ++-- docs/content/Dictionary/index.md | 19 ++++++++++--------- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/content/Dictionary/api.md b/docs/content/Dictionary/api.md index 59d994eb..b44210c0 100644 --- a/docs/content/Dictionary/api.md +++ b/docs/content/Dictionary/api.md @@ -6,6 +6,6 @@ abbreviations: # Application Programming Interface -Application Programming Interface (API) - A set of protocols, routines, and tools for building software applications. APIs specify how software components should interact and are used when programming graphical user interface (GUI) components. +An Application Programming Interface (API) is a set of rules for communication between software components. -**Example**: The [GitHub](github.md) API allows developers to interact with GitHub repositories, issues, and pull requests programmatically. +**Example**: Developers use the [GitHub](github.md) API to work with repositories, issues, and pull requests from scripts. diff --git a/docs/content/Dictionary/index.md b/docs/content/Dictionary/index.md index d78d688f..183161f7 100644 --- a/docs/content/Dictionary/index.md +++ b/docs/content/Dictionary/index.md @@ -1,8 +1,8 @@ # Glossary -Welcome to the PSModule Glossary, a reference of terms, concepts, and technologies used throughout our projects and documentation. +This glossary is a reference for terms, concepts, and technologies in PSModule projects and documentation. -## Table of Contents +## Table of contents - [API](api.md) - [Azure](azure.md) @@ -36,9 +36,10 @@ Welcome to the PSModule Glossary, a reference of terms, concepts, and technologi - [Workflow](workflow.md) - [YAML](yaml.md) -## Quick Reference +## Quick reference + +The quick reference lists common PSModule terms. -Common terms you might encounter: - [API](api.md) - Application Programming Interface - [Azure](azure.md) - Microsoft's cloud platform - [CI/CD](ci-cd.md) - Continuous Integration/Continuous Deployment @@ -55,10 +56,10 @@ Common terms you might encounter: ## Overview -This glossary serves as a reference for developers, contributors, and users to understand the terminology and concepts used in PSModule projects. Each entry includes clear definitions, usage examples, and related links where applicable. +Each entry gives a definition. Some entries also include examples and links to related terms. -!!! info "Contributing to the Glossary" - Found a term that should be added or need to update an existing definition? Please [create an issue](https://github.com/PSModule/Process-PSModule/issues) or submit a pull request with your suggestions. +!!! info "Contributing to the glossary" + To add a term or correct a definition, [create an issue](https://github.com/PSModule/Process-PSModule/issues) or submit a pull request. -!!! tip "Search Functionality" - Use the search feature in the top navigation to quickly find specific terms and their definitions across the entire documentation site. +!!! tip "Search functionality" + Use the search field in the top navigation to find terms and definitions across the documentation site. From 88b9f46ab0d7ea8739db243ab1f374795c19b944 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 13:28:26 +0100 Subject: [PATCH 2/4] Clarify workflow and integration glossary definitions --- docs/content/Dictionary/azure-functions.md | 2 +- docs/content/Dictionary/branch.md | 4 ++-- docs/content/Dictionary/ci-cd.md | 6 +++++- docs/content/Dictionary/github-actions.md | 4 ++-- docs/content/Dictionary/github.md | 2 +- docs/content/Dictionary/index.md | 2 +- docs/content/Dictionary/pipeline.md | 2 +- docs/content/Dictionary/pull-request.md | 2 +- docs/content/Dictionary/rest-api.md | 4 +++- docs/content/Dictionary/workflow.md | 4 ++-- 10 files changed, 19 insertions(+), 13 deletions(-) diff --git a/docs/content/Dictionary/azure-functions.md b/docs/content/Dictionary/azure-functions.md index 3a014d80..cdea0d6d 100644 --- a/docs/content/Dictionary/azure-functions.md +++ b/docs/content/Dictionary/azure-functions.md @@ -5,4 +5,4 @@ abbreviations: [] # Azure Functions -A serverless compute service that lets you run event-triggered code without having to explicitly provision or manage infrastructure. +Azure Functions runs code in response to events. Serverless hosting options manage the infrastructure that runs the code. diff --git a/docs/content/Dictionary/branch.md b/docs/content/Dictionary/branch.md index 357ca156..411a4aca 100644 --- a/docs/content/Dictionary/branch.md +++ b/docs/content/Dictionary/branch.md @@ -5,6 +5,6 @@ abbreviations: [] # Branch -In version control systems like [Git](git.md), a branch is a parallel version of a [repository](repository.md) that diverges from the main working project. +In version control, a branch is an independent line of development. In [Git](git.md), it points to a commit in a [repository](repository.md). -**Example**: Feature branches are used to develop new features in isolation before merging back to the main branch. +**Example**: Feature branches keep work separate before developers merge it into the main branch. diff --git a/docs/content/Dictionary/ci-cd.md b/docs/content/Dictionary/ci-cd.md index 17a1b244..cfc42236 100644 --- a/docs/content/Dictionary/ci-cd.md +++ b/docs/content/Dictionary/ci-cd.md @@ -8,4 +8,8 @@ abbreviations: # Continuous Integration and Continuous Deployment -Continuous Integration/Continuous Deployment (CI/CD) - A software development practice where developers regularly merge their code changes into a central repository, after which automated builds and tests are run. +CI/CD combines Continuous Integration with Continuous Delivery or Continuous Deployment. + +Continuous Integration (CI) uses automated builds and tests when developers merge code changes into a shared repository. + +Continuous Delivery keeps tested changes ready for production deployment. Continuous Deployment automatically deploys each change that passes the pipeline to production. diff --git a/docs/content/Dictionary/github-actions.md b/docs/content/Dictionary/github-actions.md index 8fe876d9..74a38314 100644 --- a/docs/content/Dictionary/github-actions.md +++ b/docs/content/Dictionary/github-actions.md @@ -6,6 +6,6 @@ abbreviations: # GitHub Actions -[GitHub's](github.md) built-in [CI/CD](ci-cd.md) platform that allows you to automate your build, test, and deployment [pipeline](pipeline.md). +GitHub Actions is [GitHub's](github.md) [CI/CD](ci-cd.md) platform. It automates build, test, and deployment tasks in a [pipeline](pipeline.md). -**Example**: Automatically running tests when a [pull request](pull-request.md) is created. +**Example**: A workflow runs tests when a contributor creates a [pull request](pull-request.md). diff --git a/docs/content/Dictionary/github.md b/docs/content/Dictionary/github.md index d1de21b4..3b5b6371 100644 --- a/docs/content/Dictionary/github.md +++ b/docs/content/Dictionary/github.md @@ -7,4 +7,4 @@ abbreviations: # GitHub -A web-based platform for version control and collaboration that lets you and others work together on projects from anywhere. +GitHub is a web-based platform for version control and collaboration. diff --git a/docs/content/Dictionary/index.md b/docs/content/Dictionary/index.md index 183161f7..b49de8fe 100644 --- a/docs/content/Dictionary/index.md +++ b/docs/content/Dictionary/index.md @@ -42,7 +42,7 @@ The quick reference lists common PSModule terms. - [API](api.md) - Application Programming Interface - [Azure](azure.md) - Microsoft's cloud platform -- [CI/CD](ci-cd.md) - Continuous Integration/Continuous Deployment +- [CI/CD](ci-cd.md) - Continuous Integration with Continuous Delivery or Continuous Deployment - [Cmdlet](cmdlet.md) - PowerShell command - [Git](git.md) - Version control system - [GitHub](github.md) - Code hosting platform diff --git a/docs/content/Dictionary/pipeline.md b/docs/content/Dictionary/pipeline.md index b42407b5..2654e1f4 100644 --- a/docs/content/Dictionary/pipeline.md +++ b/docs/content/Dictionary/pipeline.md @@ -5,4 +5,4 @@ abbreviations: [] # Pipeline -A series of automated processes that allow developers and [DevOps](devops.md) professionals to reliably and efficiently compile, build, and deploy their code. +A pipeline is a series of automated processes that developers and [DevOps](devops.md) teams use to compile, build, and deploy code. diff --git a/docs/content/Dictionary/pull-request.md b/docs/content/Dictionary/pull-request.md index abefc5b6..5805396d 100644 --- a/docs/content/Dictionary/pull-request.md +++ b/docs/content/Dictionary/pull-request.md @@ -5,4 +5,4 @@ abbreviations: [] # Pull Request -Pull Request (PR) - A method of submitting contributions to a software project where changes are proposed and reviewed before being merged into the main codebase. +A Pull Request (PR) proposes changes to a software project for review before a merge into the codebase. diff --git a/docs/content/Dictionary/rest-api.md b/docs/content/Dictionary/rest-api.md index c56ad28a..bc3c2c85 100644 --- a/docs/content/Dictionary/rest-api.md +++ b/docs/content/Dictionary/rest-api.md @@ -8,4 +8,6 @@ abbreviations: # Representational State Transfer API -An architectural style for designing web services that uses HTTP requests to GET, PUT, POST, and DELETE data. +A REST API is an interface for a web service that follows the Representational State Transfer (REST) architectural style. + +Clients use HTTP methods such as `GET`, `PUT`, `POST`, and `DELETE` to work with resources. diff --git a/docs/content/Dictionary/workflow.md b/docs/content/Dictionary/workflow.md index 86c600c0..6924b4db 100644 --- a/docs/content/Dictionary/workflow.md +++ b/docs/content/Dictionary/workflow.md @@ -5,6 +5,6 @@ abbreviations: [] # Workflow -A series of automated steps or processes that execute in response to specific events or triggers. +A workflow is an automated process that runs in response to an event or trigger. -**Example**: A [GitHub Actions](github-actions.md) workflow that runs tests every time code is pushed to a [repository](repository.md). +**Example**: A [GitHub Actions](github-actions.md) workflow runs tests each time a contributor pushes code to a [repository](repository.md). From 1d1db67f2956d035a36b140994d84cf1f625a105 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 13:29:47 +0100 Subject: [PATCH 3/4] State tool and format definitions in active prose --- docs/content/Dictionary/cmdlet.md | 2 +- docs/content/Dictionary/docker.md | 2 +- docs/content/Dictionary/lts.md | 5 +++-- docs/content/Dictionary/markdown.md | 2 +- docs/content/Dictionary/mkdocs.md | 2 +- docs/content/Dictionary/powershell.md | 2 +- docs/content/Dictionary/semantic-versioning.md | 2 +- docs/content/Dictionary/template.md | 2 +- docs/content/Dictionary/yaml.md | 4 ++-- 9 files changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/content/Dictionary/cmdlet.md b/docs/content/Dictionary/cmdlet.md index 364bf230..70761b5a 100644 --- a/docs/content/Dictionary/cmdlet.md +++ b/docs/content/Dictionary/cmdlet.md @@ -5,6 +5,6 @@ abbreviations: [] # Cmdlet -A lightweight [PowerShell](powershell.md) command that follows the verb-noun naming convention and is designed to perform a specific function. +A cmdlet is a lightweight [PowerShell](powershell.md) command that performs a specific task and follows the verb-noun naming convention. **Example**: `Get-Process`, `Set-Location`, `New-Item` diff --git a/docs/content/Dictionary/docker.md b/docs/content/Dictionary/docker.md index 018df514..add71f2b 100644 --- a/docs/content/Dictionary/docker.md +++ b/docs/content/Dictionary/docker.md @@ -5,4 +5,4 @@ abbreviations: [] # Docker -A platform for developing, shipping, and running applications using containerization technology. +Docker is a platform with tools to develop, distribute, and run applications in containers. diff --git a/docs/content/Dictionary/lts.md b/docs/content/Dictionary/lts.md index cb25293f..681f47a0 100644 --- a/docs/content/Dictionary/lts.md +++ b/docs/content/Dictionary/lts.md @@ -6,5 +6,6 @@ abbreviations: # Long-Term Servicing -Long-Term Servicing (LTS). -For more info visit: [PowerShell Support Lifecycle](https://learn.microsoft.com/en-us/powershell/scripting/install/powershell-support-lifecycle?view=powershell-7.5) +PowerShell Long-Term Servicing (LTS) releases use .NET LTS releases. + +See [PowerShell Support Lifecycle](https://learn.microsoft.com/en-us/powershell/scripting/install/powershell-support-lifecycle?view=powershell-7.5) for support policies and end-of-support dates. diff --git a/docs/content/Dictionary/markdown.md b/docs/content/Dictionary/markdown.md index cceefddf..ca39fc6c 100644 --- a/docs/content/Dictionary/markdown.md +++ b/docs/content/Dictionary/markdown.md @@ -5,4 +5,4 @@ abbreviations: [] # Markdown -A lightweight markup language with plain text formatting syntax, designed to be converted to HTML and many other formats. +Markdown is a lightweight markup language that uses plain text syntax. Tools convert Markdown documents to HTML and other formats. diff --git a/docs/content/Dictionary/mkdocs.md b/docs/content/Dictionary/mkdocs.md index 9439e55f..af555469 100644 --- a/docs/content/Dictionary/mkdocs.md +++ b/docs/content/Dictionary/mkdocs.md @@ -6,4 +6,4 @@ abbreviations: # MkDocs -A fast, simple static site generator that's geared towards building project documentation using [Markdown](markdown.md) files. +MkDocs is a static site generator for project documentation. It builds sites from [Markdown](markdown.md) files. diff --git a/docs/content/Dictionary/powershell.md b/docs/content/Dictionary/powershell.md index 6c078e6f..3c3c01b6 100644 --- a/docs/content/Dictionary/powershell.md +++ b/docs/content/Dictionary/powershell.md @@ -5,4 +5,4 @@ abbreviations: [] # PowerShell -A task automation and configuration management framework from Microsoft, consisting of a command-line shell and the associated scripting language. +PowerShell is a task automation and configuration management framework from Microsoft. It includes a command-line shell and a scripting language. diff --git a/docs/content/Dictionary/semantic-versioning.md b/docs/content/Dictionary/semantic-versioning.md index 07406d65..d96a7243 100644 --- a/docs/content/Dictionary/semantic-versioning.md +++ b/docs/content/Dictionary/semantic-versioning.md @@ -5,6 +5,6 @@ abbreviations: [] # Semantic Versioning -Semantic Versioning (SemVer) - A versioning scheme that uses a three-part version number: MAJOR.MINOR.PATCH, where each part is incremented based on the type of changes made. +Semantic Versioning (SemVer) uses the three-part version format `MAJOR.MINOR.PATCH`. The version number indicates whether a change affects compatibility, adds functionality, or fixes a bug. **Example**: Version 1.2.3 where 1 is major, 2 is minor, and 3 is patch. diff --git a/docs/content/Dictionary/template.md b/docs/content/Dictionary/template.md index 6bf53e46..8d805103 100644 --- a/docs/content/Dictionary/template.md +++ b/docs/content/Dictionary/template.md @@ -5,4 +5,4 @@ abbreviations: [] # Template -A pre-designed format or structure that can be used as a starting point for creating new files, projects, or configurations. +A template gives a format or structure for new files, projects, or configurations. diff --git a/docs/content/Dictionary/yaml.md b/docs/content/Dictionary/yaml.md index b5cd9eff..faf862ff 100644 --- a/docs/content/Dictionary/yaml.md +++ b/docs/content/Dictionary/yaml.md @@ -6,6 +6,6 @@ abbreviations: # YAML Ain't Markup Language -YAML Ain't Markup Language (YAML) - A human-readable data serialization standard commonly used for configuration files and data exchange. +YAML Ain't Markup Language (YAML) is a human-readable data serialization standard. Applications use YAML for configuration files and data exchange. -**Example**: [GitHub Actions](github-actions.md) workflows are defined using YAML files. +**Example**: [GitHub Actions](github-actions.md) workflows use YAML files. From e0dd865ff0973a0eef3b3a75a0fac81ff1541592 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 13:32:19 +0100 Subject: [PATCH 4/4] Align abbreviation tooltips with canonical terminology --- docs/includes/abbreviations.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/includes/abbreviations.md b/docs/includes/abbreviations.md index e158693f..b013a7b3 100644 --- a/docs/includes/abbreviations.md +++ b/docs/includes/abbreviations.md @@ -3,13 +3,13 @@ *[CD]: Continuous Deployment or Continuous Delivery *[CDN]: Content Delivery Network *[CI]: Continuous Integration -*[CI/CD]: Continuous Integration/Continuous Deployment +*[CI/CD]: Continuous Integration with Continuous Delivery or Continuous Deployment *[CLI]: Command Line Interface *[CRUD]: Create, Read, Update, Delete *[CSS]: Cascading Style Sheets *[DevOps]: Development and Operations *[DNS]: Domain Name System -*[Docker]: Platform for developing, shipping, and running applications in containers +*[Docker]: Platform with tools to develop, distribute, and run applications in containers *[GH]: GitHub *[GHE]: GitHub Enterprise *[GHEC]: GitHub Enterprise Cloud @@ -19,7 +19,7 @@ *[Git]: Version Control System *[GitHub]: Web-based platform for version control using Git *[GitLab]: Web-based DevOps lifecycle tool that provides a Git repository manager -*[HTML]: Hyper Text Markup Language +*[HTML]: HyperText Markup Language *[HTTP]: Hypertext Transfer Protocol *[HTTPS]: Hypertext Transfer Protocol Secure *[IaaS]: Infrastructure as a Service @@ -35,7 +35,7 @@ *[ps1xml]: PowerShell XML File *[psd1]: PowerShell Data File *[psm1]: PowerShell Module File -*[pwsh]: PowerShell Core (also known as PowerShell 7) +*[pwsh]: PowerShell 7 command-line executable *[REST]: Representational State Transfer *[SaaS]: Software as a Service *[SEO]: Search Engine Optimization @@ -47,4 +47,4 @@ *[UX]: User Experience *[VPN]: Virtual Private Network *[W3C]: World Wide Web Consortium -*[XML]: eXtensible Markup Language +*[XML]: Extensible Markup Language