How to add examples to a cmdlet help topic
Note
Manual authoring of XML-based help is very difficult. The PlatyPS module allows you to write help in Markdown and then convert it to XML-based help. This makes it much easier to write and maintain help. PlatyPS can also create the Updateable Help packages for you. For more information, see Create XML-based help using PlatyPS.
List all of the parameter names in the command, even when the parameter names are optional. This helps the user to interpret the command easily.
Avoid aliases and partial parameter names, even though they work in PowerShell.
In the example description, explain the rational for the construction of the command. Explain why you chose particular parameters and values, and how you use variables.
If the command uses expressions, explain them in detail.
If the command uses properties and methods of objects, especially properties that don't appear in the default display, use the example as an opportunity tell the user about the object.
Examples appear only in the Detailed and Full views of cmdlet Help.
The following XML shows how to add an Examples node that contains a single Example node. Add additional example nodes for each examples you want to include in the topic.
<command:examples>
<command:example>
</command:example>
</command:examples>
The following XML shows how to add a title for the example. The title is used to set the example apart from other examples. PowerShell uses a standard header that includes a sequential example number.
<command:examples>
<command:example>
<maml:title>---------- EXAMPLE 1 ----------</maml:title>
</command:example>
</command:examples>
The following XML shows how to add characters, such as the Windows PowerShell prompt, that are
displayed immediately before the example command (without any intervening spaces). PowerShell uses
the Windows PowerShell prompt: C:\PS>
.
<command:examples>
<command:example>
<maml:title>---------- EXAMPLE 1 ----------</maml:title>
<maml:introduction>
<maml:para>C:\PS></maml:para>
</maml:introduction>
</command:example>
</command:examples>
The following XML shows how to add the actual command of the example. When adding the command, type the entire name (do not use alias) of cmdlets and parameters. Also, use lowercase characters whenever possible.
<command:examples>
<command:example>
<maml:title>---------- EXAMPLE 1 ----------</maml:title>
<maml:introduction>
<maml:para>C:\PS></maml:para>
</maml:introduction>
<dev:code> command </dev:code>
</command:example>
</command:examples>
The following XML shows how to add a description for the example. PowerShell uses a single set of
<maml:para>
tags for the description, even though multiple <maml:para>
tags can be used.
<command:examples>
<command:example>
<maml:title>---------- EXAMPLE 1 ----------</maml:title>
<maml:introduction>
<maml:para>C:\PS></maml:para>
</maml:introduction>
<dev:code> command </dev:code>
<dev:remarks>
<maml:para> command description </maml:para>
</dev:remarks>
</command:example>
</command:examples>
The following XML shows how to add the output of the command. The command results information is
optional, but in some cases it's helpful to demonstrate the effect of using specific parameters.
PowerShell uses two sets of blank <maml:para>
tags to separate the command output from the
command.
<command:examples>
<command:example>
<maml:title>---------- EXAMPLE 1 ----------</maml:title>
<maml:introduction>
<maml:para>C:\PS></maml:para>
</maml:introduction>
<dev:code> command </dev:code>
<dev:remarks>
<maml:para> command description </maml:para>
<maml:para></maml:para>
<maml:para></maml:para>
<maml:para> command output </maml:para>
</dev:remarks>
</command:example>
</command:examples>
PowerShell feedback
PowerShell is an open source project. Select a link to provide feedback: