
close
close
When you create PowerShell tools, good help documentation should be an important part of your development process. PowerShell’s help system does a good job at looking at your command and providing basic help. You can and should provide more information about what your tool does and how to use it. To create PowerShell help in a function typically means using comment-based help. This is generally pretty easy to do in the ISE because you can create your own snippets or simply copy, paste, and edit.
The downside is that if you need to update the help, then you also need to update the script. If you are using digital signatures that means you have to re-sign the script. Another potential downside is that if you need to localize help for a different language, it is much more complicated using comment-based help. The alternative is to use Microsoft’s XML help format. Trust me when I say that creating an XML help file from scratch is an awful experience. That’s because the format isn’t simple XML, it is a specialized format called MAML. If you can get through it, then the benefit is that help documentation is in a separate file, which makes it easier to update and localize.
To help you meet these goals, SAPIEN Technologies released a new product called PowerShell Help Writer. You can download a 45-day evaluation copy from their online store. I’m going to give you a taste of what to expect based on v1.0.9. SAPIEN has always been great at keeping their products up-to-date and responding to customers so your experience might be different. To use the product, you’ll need at least PowerShell 2.0 on Windows 7 and .NET Framework 4.0. Let’s begin.
The setup process is quite easy, as it is for all SAPIEN products.
SAPIEN’s PowerShell Help Writer 2015 Setup Wizard. (Image Credit: Jeff Hicks)
SAPIEN’s PowerShell Help Writer 2015 license agreement. (Image Credit: Jeff Hicks)
Custom installation for SAPIEN’s PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)
Selecting features to install during SAPIEN’s wizard setup. (Image Credit: Jeff Hicks)
SAPIEN’s Setup Wizard is ready to begin installation. (Image Credit: Jeff Hicks)
SAPIEN’s PowerShell Help Writer 2015 start page. (Image Credit: Jeff Hicks)
Disabling SAPIEN’s PowerShell Help Writer 2015 start page. (Image Credit: Jeff Hicks)
Creating a new help file in SAPIEN’s PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)
Entering information for the new help file in SAPIEN’s PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)
The add parameters icon in SAPIEN PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)
An alternative way to add a parameter in SAPIEN PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)
Right click to add a parameter set in SAPIEN PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)
Saving the help file in SAPIEN PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)
Including a related link in our help file in SAPIEN PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)
Defining a note in SAPIEN PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)
Option to edit the file as XML in SAPIEN PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)
# .ExternalHelp Test-Service-Help.xml
Although the XML file is in a subfolder, PowerShell knows to search culture-defined subfolders. Another benefit to external help is that it can cut down on the size of your script file. In PowerShell, I can dot source my script file and look at help.
advertisment
. c:\scripts\test-service.ps1
help test-service -showwindow
Test-Service Help. (Image Credit: Jeff Hicks)
Exporting the help file to a module folder. (Image Credit: Jeff Hicks)
PowerShell Help Writer generates complete MAML help, including parameter sets. (Image Credit: Jeff Hicks)
More from Jeff Hicks
advertisment
Petri Newsletters
Whether it’s Security or Cloud Computing, we have the know-how for you. Sign up for our newsletters here.
advertisment
More in PowerShell
Microsoft’s New PowerShell Crescendo Tool Facilitates Native Command-Line Wraps
Mar 21, 2022 | Rabia Noureen
Most popular on petri
Log in to save content to your profile.
Article saved!
Access saved content from your profile page. View Saved
Join The Conversation
Create a free account today to participate in forum conversations, comment on posts and more.
Copyright ©2019 BWW Media Group