Define common terminology and styling #12632

sdwheeler · 2026-01-05T16:14:55Z

PR Summary

Define common terminology and styling

Fixes AB#543257

PR Checklist

Descriptive Title: This PR's title is a synopsis of the changes it proposes.
Summary: This PR's summary describes the scope and intent of the change.
Contributor's Guide: I have read the contributor's guide.
Style: This PR adheres to the style guide.

sdwheeler · 2026-01-05T16:16:22Z

@surfingoldelephant Please review and comment. We can build on this document.

Copilot

Pull request overview

This PR introduces a new terminology guidelines document for PowerShell documentation to ensure consistency across documentation. The document covers common terminology, styling conventions, and formatting rules that will eventually be incorporated into the PowerShell-Docs Style Guide.

Establishes terminology standards for null values, boolean values, hash tables, and PowerShell language constructs
Defines hyphenation, capitalization, and spacing conventions for PowerShell-specific terms
Provides guidance on distinguishing between similar concepts (declare vs. initialize, native vs. external commands, scalar vs. single vs. singleton)

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

terminology.md

learn-build-service-prod · 2026-01-05T16:19:08Z

Learn Build status updates of commit 2d052a0:

✅ Validation status: passed

File	Status	Preview URL	Details
terminology.md	✅Succeeded

For more details, please refer to the build report.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

learn-build-service-prod · 2026-01-05T18:58:38Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-01-05T19:02:46Z

Learn Build status updates of commit 5be5a08:

✅ Validation status: passed

File	Status	Preview URL	Details
terminology.md	✅Succeeded

For more details, please refer to the build report.

learn-build-service-prod · 2026-01-05T21:56:20Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-01-05T22:00:13Z

Learn Build status updates of commit d8fea64:

✅ Validation status: passed

File	Status	Preview URL	Details
terminology.md	✅Succeeded

For more details, please refer to the build report.

terminology.md

surfingoldelephant · 2026-01-06T12:54:04Z

terminology.md

+PowerShell has no concept of declaring variables, unless you count using `New-Variable` as a
+declaration. Even then, the new variable is given a default value. Essentially, variables are
+declared on first use. If the variable was not assigned a value, it is initialized to a default
+value depending on its type.


New-Variable -Name Foo creates a new variable $foo with a value of $null. Are we considering $null as a "default value" in this case?

Fair point. After looking at it more closely, New-Variable doesn't allow you to specify a type. So, basically, this is the only way to declare a variable without initialization. I will reword this.

surfingoldelephant · 2026-01-06T12:58:44Z

terminology.md

+- Use _hashtable_ (all lowercase) when referring to the PowerShell objects of type `[hashtable]`.
+  May be capitalized as _Hashtable_ when it begins a sentence.


Based on this, does about_Hash_Tables need to be renamed to about_Hashtables?

Technically, yes. But practically, no. Update-Help doesn't have a way to rename files. If you have help already installed you end up with both files. So we can't really rename about_ files.

terminology.md

surfingoldelephant · 2026-01-06T13:00:41Z

terminology.md

+
+- A _statement block_ to refers to `{}` expressions in a statement. This is how the AST refers to
+  them. Statement blocks don't take parameters or create new scopes.
+- _scriptblock_ should be used to refer to `{}` expressions of type `[scriptblock]`. For example,


Similar to above. about_Script_Blocks will need to be renamed to about_Scriptblocks.

Same answer

surfingoldelephant · 2026-01-06T13:03:38Z

terminology.md

+_Native commands_ are executables that can be run from any shell or other invocation method
+supported by the OS.
+
+### Scalar vs. single vs. singleton


"Scalar" is most commonly used in reference to scalars vs collections in PowerShell. E.g.,

"When the left-hand side operand is a scalar value, -eq returns a boolean value. When the operand is a collection, -eq acts as a filter and returns matching items from the collection.

I think this section should specifically draw the comparison between scalar vs collection.

Yeah, that is not really accurate. It should be singleton instead of scalar.

terminology.md

Co-authored-by: surfingoldelephant <151538956+surfingoldelephant@users.noreply.github.com>

learn-build-service-prod · 2026-01-06T15:05:13Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-01-06T15:06:17Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-01-06T15:08:39Z

Learn Build status updates of commit 35cdc75:

✅ Validation status: passed

File	Status	Preview URL	Details
terminology.md	✅Succeeded

For more details, please refer to the build report.

learn-build-service-prod · 2026-01-06T15:13:01Z

Learn Build status updates of commit 9eaac16:

✅ Validation status: passed

File	Status	Preview URL	Details
terminology.md	✅Succeeded

For more details, please refer to the build report.

Co-authored-by: surfingoldelephant <151538956+surfingoldelephant@users.noreply.github.com>

learn-build-service-prod · 2026-01-06T15:15:51Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-01-06T15:20:14Z

Learn Build status updates of commit 49495f5:

✅ Validation status: passed

File	Status	Preview URL	Details
terminology.md	✅Succeeded

For more details, please refer to the build report.

learn-build-service-prod · 2026-01-06T15:58:10Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-01-06T16:01:03Z

Learn Build status updates of commit 3ebe06b:

✅ Validation status: passed

File	Status	Preview URL	Details
terminology.md	✅Succeeded

For more details, please refer to the build report.

learn-build-service-prod · 2026-01-06T16:20:42Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-01-06T16:23:45Z

Learn Build status updates of commit 1deca1b:

✅ Validation status: passed

File	Status	Preview URL	Details
terminology.md	✅Succeeded

For more details, please refer to the build report.

Define common terminology and styling

2d052a0

sdwheeler requested a review from michaeltlombardi as a code owner January 5, 2026 16:14

Copilot AI review requested due to automatic review settings January 5, 2026 16:14

Copilot started reviewing on behalf of sdwheeler January 5, 2026 16:15 View session

This comment was marked as outdated.

Sign in to view

Copilot AI reviewed Jan 5, 2026

View reviewed changes

terminology.md Outdated Show resolved Hide resolved

terminology.md Outdated Show resolved Hide resolved

terminology.md Outdated Show resolved Hide resolved

This comment was marked as outdated.

Sign in to view

sdwheeler and others added 2 commits January 5, 2026 12:57

Apply suggestions from code review

9c90c8b

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Add not about Env:

5be5a08

sdwheeler force-pushed the sdw-w543257-terms branch from 88ee6cb to 5be5a08 Compare January 5, 2026 18:57

This comment was marked as outdated.

Sign in to view

Add section for $_/$PSItem

d8fea64