From e83d12ddeeba9ec93b7fde9abc0862adc249c09f Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 24 Sep 2025 14:09:23 -0500 Subject: [PATCH 1/4] Upcase H2 headers --- .../About/about_Environment_Variables.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index 93286cd1f36..ca8de9debe7 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -25,6 +25,8 @@ programs. PowerShell creates the following environment variables: For full descriptions of these variables, see the [PowerShell environment variables][03] of this article. +## LONG DESCRIPTION + PowerShell can access and manage environment variables in any of the supported operating system platforms. The PowerShell Environment provider lets you get, add, change, clear, and delete environment variables in the current console. From b1671ad056e5481cbb0b365ab49748d52f23b1c7 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 24 Sep 2025 14:29:10 -0500 Subject: [PATCH 2/4] Fix structure of About files --- .../About/about_Environment_Variables.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index ca8de9debe7..93286cd1f36 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -25,8 +25,6 @@ programs. PowerShell creates the following environment variables: For full descriptions of these variables, see the [PowerShell environment variables][03] of this article. -## LONG DESCRIPTION - PowerShell can access and manage environment variables in any of the supported operating system platforms. The PowerShell Environment provider lets you get, add, change, clear, and delete environment variables in the current console. From ce60c55f11746d8c59001aed52268db3d4db5cc1 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 1 Oct 2025 09:35:17 -0500 Subject: [PATCH 3/4] Update facts for about_ files --- ...ing-help-for-windows-powershell-modules.md | 102 ++++++++++-------- 1 file changed, 59 insertions(+), 43 deletions(-) diff --git a/reference/docs-conceptual/developer/help/writing-help-for-windows-powershell-modules.md b/reference/docs-conceptual/developer/help/writing-help-for-windows-powershell-modules.md index 8a825f73b47..c715113a6df 100644 --- a/reference/docs-conceptual/developer/help/writing-help-for-windows-powershell-modules.md +++ b/reference/docs-conceptual/developer/help/writing-help-for-windows-powershell-modules.md @@ -1,6 +1,6 @@ --- description: Writing Help for PowerShell Modules -ms.date: 09/22/2025 +ms.date: 10/01/2025 title: Writing Help for PowerShell Modules --- # Writing Help for PowerShell Modules @@ -33,48 +33,64 @@ A module can include the following types of Help. You can use a conceptual ("about") Help topic to describe the module and its members and to explain how the members can be used together to perform tasks. By default, PowerShell includes - over 100 of these conceptual About Help topics. - - - Conceptual Help topics are text files with UTF-8 with BOM encoding. - - The filename must use the `about_.help.txt` format, such as `about_MyModule.help.txt`. - - For best display results, you should limit the length of each line to 80 characters. - - You can use the following sample template as a starting point for writing conceptual Help - topics. - - > [!NOTE] - > The `TOPIC` section header must start in the first column of the first line of the file. The - > section content on the second line should match the filename, without the `.help.txt` suffix. - > You must indent the content exactly 5 spaces. The third line must be blank. The - > `SHORT DESCRIPTION` section header must start in the first column of the fourth line. You must - > indent the content on the fifth line exactly 5 spaces. These requirements are necessary for - > the `Get-Help` cmdlet to recognize the content correctly. - - ``` - TOPIC - about_ - - SHORT DESCRIPTION - A short, one-line description of the topic contents. - - LONG DESCRIPTION - A detailed, full description of the subject or purpose of the module. - - EXAMPLES - Examples of how to use the module or how the subject feature works in - practice. - - KEYWORDS - Terms or titles on which you might expect your users to search for the - information in this topic. - - SEE ALSO - Text-only references for further reading. Hyperlinks can't work in the - PowerShell console. - ``` - - Except for the first two sections, the structure of conceptual Help topics is arbitrary. The - remaining section titles can be whatever is appropriate for your content. By convention, you - should use the same capitalization, indentation, and blank line separations. + over 100 of these conceptual About Help topics. The filename must use the `about_.help.txt` + format, such as `about_MyModule.help.txt`. + + > [!NOTE] + > The `TOPIC` section header must start in the first column of the first line of the file. The + > section content on the second line should match the filename, without the `.help.txt` suffix. + > You must indent the content exactly 4 spaces. The third line must be blank. The `SYNOPSIS` + > section header must start in the first column of the fourth line. You must indent the content + > on the fifth line exactly 4 spaces. These requirements are necessary for the `Get-Help` cmdlet + > to recognize the content correctly. + + ``` + TOPIC + about_ + + SYNOPSIS + A short, one-line description of the topic contents. + ``` + + You can use the following sample template as a starting point for writing conceptual Help topics. + Except for the first two sections, the structure of conceptual Help topics is arbitrary. The + remaining section titles can be whatever is appropriate for your content. + + ``` + TOPIC + about_ + + SYNOPSIS + A short, one-line description of the topic contents. + + LONG DESCRIPTION + + A detailed, full description of the subject or purpose of the module. + + EXAMPLES + + Examples of how to use the module or how the subject feature works in + practice. + + TROUBLESHOOTING + + Instructions for resolving common problems. + + SEE ALSO + + Text-only references for further reading. Hyperlinks can't work in the + PowerShell console. + ``` + + You can use any style and markup you want, but PowerShell sees it as plain text and there is no + special rendering of the text in the PowerShell console. The following suggestions ensure the best + display results and readability. + + - UTF-8 with BOM encoding to ensure any special (multi-byte) characters display correctly. + - Underline section headers or use all uppercase letters to make them stand out. This makes the + content easier to scan. + - Limit the length of each line to 80 characters. + - Indent code blocks and example output to separate them from the surrounding prose. ## Placement of Module Help From 782cfb166f70b0ccb68dc8e3064720695452388d Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 1 Oct 2025 09:42:49 -0500 Subject: [PATCH 4/4] Fix grammatical error in PowerShell help writing tips Corrected grammatical error in help writing guidelines. --- .../help/writing-help-for-windows-powershell-modules.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/docs-conceptual/developer/help/writing-help-for-windows-powershell-modules.md b/reference/docs-conceptual/developer/help/writing-help-for-windows-powershell-modules.md index c715113a6df..2d7ddc6b7bc 100644 --- a/reference/docs-conceptual/developer/help/writing-help-for-windows-powershell-modules.md +++ b/reference/docs-conceptual/developer/help/writing-help-for-windows-powershell-modules.md @@ -86,8 +86,8 @@ A module can include the following types of Help. special rendering of the text in the PowerShell console. The following suggestions ensure the best display results and readability. - - UTF-8 with BOM encoding to ensure any special (multi-byte) characters display correctly. - - Underline section headers or use all uppercase letters to make them stand out. This makes the + - Use UTF-8 with BOM encoding to ensure any special (multi-byte) characters display correctly. + - Underline section headers or use all uppercase letters to make they stand out. This makes the content easier to scan. - Limit the length of each line to 80 characters. - Indent code blocks and example output to separate them from the surrounding prose.