|
1 | 1 | --- |
2 | 2 | description: Writing Help for PowerShell Modules |
3 | | -ms.date: 09/22/2025 |
| 3 | +ms.date: 10/01/2025 |
4 | 4 | title: Writing Help for PowerShell Modules |
5 | 5 | --- |
6 | 6 | # Writing Help for PowerShell Modules |
@@ -33,48 +33,64 @@ A module can include the following types of Help. |
33 | 33 |
|
34 | 34 | You can use a conceptual ("about") Help topic to describe the module and its members and to |
35 | 35 | explain how the members can be used together to perform tasks. By default, PowerShell includes |
36 | | - over 100 of these conceptual About Help topics. |
37 | | - |
38 | | - - Conceptual Help topics are text files with UTF-8 with BOM encoding. |
39 | | - - The filename must use the `about_<name>.help.txt` format, such as `about_MyModule.help.txt`. |
40 | | - - For best display results, you should limit the length of each line to 80 characters. |
41 | | - - You can use the following sample template as a starting point for writing conceptual Help |
42 | | - topics. |
43 | | - |
44 | | - > [!NOTE] |
45 | | - > The `TOPIC` section header must start in the first column of the first line of the file. The |
46 | | - > section content on the second line should match the filename, without the `.help.txt` suffix. |
47 | | - > You must indent the content exactly 5 spaces. The third line must be blank. The |
48 | | - > `SHORT DESCRIPTION` section header must start in the first column of the fourth line. You must |
49 | | - > indent the content on the fifth line exactly 5 spaces. These requirements are necessary for |
50 | | - > the `Get-Help` cmdlet to recognize the content correctly. |
51 | | -
|
52 | | - ``` |
53 | | - TOPIC |
54 | | - about_<subject or module name> |
55 | | -
|
56 | | - SHORT DESCRIPTION |
57 | | - A short, one-line description of the topic contents. |
58 | | -
|
59 | | - LONG DESCRIPTION |
60 | | - A detailed, full description of the subject or purpose of the module. |
61 | | -
|
62 | | - EXAMPLES |
63 | | - Examples of how to use the module or how the subject feature works in |
64 | | - practice. |
65 | | -
|
66 | | - KEYWORDS |
67 | | - Terms or titles on which you might expect your users to search for the |
68 | | - information in this topic. |
69 | | -
|
70 | | - SEE ALSO |
71 | | - Text-only references for further reading. Hyperlinks can't work in the |
72 | | - PowerShell console. |
73 | | - ``` |
74 | | -
|
75 | | - Except for the first two sections, the structure of conceptual Help topics is arbitrary. The |
76 | | - remaining section titles can be whatever is appropriate for your content. By convention, you |
77 | | - should use the same capitalization, indentation, and blank line separations. |
| 36 | + over 100 of these conceptual About Help topics. The filename must use the `about_<name>.help.txt` |
| 37 | + format, such as `about_MyModule.help.txt`. |
| 38 | + |
| 39 | + > [!NOTE] |
| 40 | + > The `TOPIC` section header must start in the first column of the first line of the file. The |
| 41 | + > section content on the second line should match the filename, without the `.help.txt` suffix. |
| 42 | + > You must indent the content exactly 4 spaces. The third line must be blank. The `SYNOPSIS` |
| 43 | + > section header must start in the first column of the fourth line. You must indent the content |
| 44 | + > on the fifth line exactly 4 spaces. These requirements are necessary for the `Get-Help` cmdlet |
| 45 | + > to recognize the content correctly. |
| 46 | +
|
| 47 | + ``` |
| 48 | + TOPIC |
| 49 | + about_<subject or module name> |
| 50 | +
|
| 51 | + SYNOPSIS |
| 52 | + A short, one-line description of the topic contents. |
| 53 | + ``` |
| 54 | + |
| 55 | + You can use the following sample template as a starting point for writing conceptual Help topics. |
| 56 | + Except for the first two sections, the structure of conceptual Help topics is arbitrary. The |
| 57 | + remaining section titles can be whatever is appropriate for your content. |
| 58 | + |
| 59 | + ``` |
| 60 | + TOPIC |
| 61 | + about_<subject or module name> |
| 62 | +
|
| 63 | + SYNOPSIS |
| 64 | + A short, one-line description of the topic contents. |
| 65 | +
|
| 66 | + LONG DESCRIPTION |
| 67 | +
|
| 68 | + A detailed, full description of the subject or purpose of the module. |
| 69 | +
|
| 70 | + EXAMPLES |
| 71 | +
|
| 72 | + Examples of how to use the module or how the subject feature works in |
| 73 | + practice. |
| 74 | +
|
| 75 | + TROUBLESHOOTING |
| 76 | +
|
| 77 | + Instructions for resolving common problems. |
| 78 | +
|
| 79 | + SEE ALSO |
| 80 | +
|
| 81 | + Text-only references for further reading. Hyperlinks can't work in the |
| 82 | + PowerShell console. |
| 83 | + ``` |
| 84 | + |
| 85 | + You can use any style and markup you want, but PowerShell sees it as plain text and there is no |
| 86 | + special rendering of the text in the PowerShell console. The following suggestions ensure the best |
| 87 | + display results and readability. |
| 88 | + |
| 89 | + - Use UTF-8 with BOM encoding to ensure any special (multi-byte) characters display correctly. |
| 90 | + - Underline section headers or use all uppercase letters to make they stand out. This makes the |
| 91 | + content easier to scan. |
| 92 | + - Limit the length of each line to 80 characters. |
| 93 | + - Indent code blocks and example output to separate them from the surrounding prose. |
78 | 94 |
|
79 | 95 | ## Placement of Module Help |
80 | 96 |
|
|
![learn-build-service-prod[bot]](https://avatars.githubusercontent.com/in/237442?v=4&size=40){kind=avatar}
0 commit comments