Writing Help for PowerShell Modules

PowerShell modules can include Help topics about the module and about the module members, such as cmdlets, providers, functions and scripts. The Get-Help cmdlet displays the module Help topics in the same format as it displays Help for other PowerShell items, and users use standard Get-Help commands to get the Help topics.

This document explains the format and correct placement of module Help topics, and it suggests guidelines for module Help content.

Types of Module Help

A module can include the following types of Help.

• XML-based help

  • Cmdlet Help. The Help topics that describe cmdlets in a module are XML files that use the command help schema
  • Provider Help. The Help topics that describe providers in a module are XML files that use the provider help schema.
  • Function Help. The Help topics that describe functions in a module can be XML files that use the command help schema or comment-based Help topics within the function, or the script or script module
  • Script Help. The Help topics that describe scripts in a module can be XML files that use the command help schema or comment-based Help topics in the script or script module.
  • The $PSHOME\Schemas\PSMaml folder contains the schema files that define the XML format.

• Conceptual ("About") help text files

  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. The filename must use the about_<name>.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_<subject or module name>
  
  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_<subject or module name>
  
  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.

  • 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.

Placement of Module Help

The Get-Help cmdlet looks for module Help topic files in language-specific subdirectories of the module directory.

For example, the following directory structure diagram shows the location of the Help topics for the SampleModule module.

<ModulePath>
    \SampleModule
        \<en-US>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml
        \<fr-FR>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml

Getting Module Help

When a user imports a module into a session, the Help topics for that module are imported into the session along with the module. You can list the Help topic files in the value of the FileList key in the module manifest, but Help topics aren't affected by the Export-ModuleMember cmdlet.

You can provide module Help topics in different languages. The Get-Help cmdlet automatically displays module Help topics in the language that's specified for the current user in the Regional and Language Options item in Control Panel. In Windows Vista and later versions of Windows, Get-Help searches for the Help topics in language-specific subdirectories of the module directory in accordance with the language fallback standards established for Windows.

Beginning in PowerShell 3.0, running a Get-Help command for a cmdlet or function triggers automatic importing of the module. The Get-Help cmdlet immediately displays the contents of the help topics in the module.

If the module doesn't contain help topics and there are no help topics for the commands in the module on the user's computer, Get-Help displays auto-generated help. The auto-generated help includes the command syntax, parameters, and input and output types, but doesn't include any descriptions. The auto-generated help includes text that directs the user to try to use the Update-Help cmdlet to download help for the command from the internet or a file share. It also recommends using the Online parameter of the Get-Help cmdlet to get the online version of the help topic.

Supporting Updatable Help

Users of PowerShell 3.0 and later versions of PowerShell can download and install updated help files for a module from the internet or from a local file share. The Update-Help and Save-Help cmdlets hide the management details from the user. Users run the Update-Help cmdlet and then use the Get-Help cmdlet to read the newest help files for the module at the PowerShell command prompt. Users don't need to restart Windows or PowerShell.

Users behind firewalls and those without internet access can use Updatable Help, as well. Administrators with internet access use the Save-Help cmdlet to download and install the newest help files to a file share. Then, users use the Path parameter of the Update-Help cmdlet to get the newest help files from the file share.

Module authors can include help files in the module and use Updatable Help to update the help files, or omit help files from the module and use Updatable Help both to install and to update them.

For more information about Updatable Help, see Supporting Updatable Help.

Supporting Online Help

Users who can't or don't install updated help files on their computers often rely on the online version of module help topics. The Online parameter of the Get-Help cmdlet opens the online version of a cmdlet or advanced function help topic for the user in their default internet browser.

The Get-Help cmdlet uses the value of the HelpUri property of the cmdlet or function to find the online version of the help topic.

Beginning in PowerShell 3.0, you can help users find the online version of cmdlet and function help topics by defining the HelpUri attribute on the cmdlet class or the HelpUri property of the CmdletBinding attribute. The value of the attribute is the value of the HelpUri property of the cmdlet or function.

For more information, see Supporting Online Help.

See Also

• Writing a PowerShell Module
• Supporting Updatable Help
• Supporting Online Help