SAPIEN Technologies PowerShell Help Writer 2015 Review

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 Setup Wizard. (Image Credit: Jeff Hicks)

Naturally, I accept the license.
SAPIEN's PowerShell Help Writer 2015 license agreement. (Image Credit: Jeff Hicks)
SAPIEN’s PowerShell Help Writer 2015 license agreement. (Image Credit: Jeff Hicks)

The installation options are also typical for SAPIEN products. Although I probably won’t make any changes, I always do a custom install.
Custom installation for SAPIEN's PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)
Custom installation for SAPIEN’s PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)

I most likely have some of these features already installed from other SAPIEN installs, but I’ll just let the installer re-install them.
Selecting features to install during SAPIEN's wizard setup. (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 Setup Wizard is ready to begin installation. (Image Credit: Jeff Hicks)

The actual installation literally took about 10 seconds, where I installed on my primary system running Windows 8.1 and PowerShell 4.0. Firing up the application presents a familiar SAPIEN-style layout. The News feed items are from the SAPIEN blog.
SAPIEN's PowerShell Help Writer 2015 start page. (Image Credit: Jeff Hicks)
SAPIEN’s PowerShell Help Writer 2015 start page. (Image Credit: Jeff Hicks)

If you don’t want the Start Page, then you can disable it by configuring Options.
Disabling 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)

You can also change the default location for your new help files. For now, I’m going to stick with the default. Next, let’s create a help file. I’m going to use an existing function that already has comment based help. The new file options appear to be for a module or empty. My function is in a simple .ps1 file, so I’ll choose Empty.
Creating a new help file in SAPIEN's PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)
Creating a new help file in SAPIEN’s PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)

I can easily type the name of the command and enter a synopsis and description. In my case, I can save some time by copying and pasting.
Entering information for the 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)

To add parameters, I can click the icon:
The add parameters icon in SAPIEN PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)
The add parameters icon in SAPIEN PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)

Or I can click the menu item to add a new parameter which provides an easy to use entry form to describe the parameter.
An alternative way to add a parameter 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)

If you are building from scratch, you’ll also need to create at least one parameter set. You can right-click and create a new one.
Right click to add a parameter set 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)

In the new parameter set, you can add new parameters. You can also right click an entry under All Parameters, copy it, select the parameter set and paste it. If you don’t do this, then you won’t have any syntax settings in help display.
At this point, I’ll save the file. Remember, I’m using the default location.
Saving the help file in SAPIEN PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)
Saving the help file in SAPIEN PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)

The suggested naming convention is commandname-help.xml. My function is called Test-Service, so I’ll save the file as Test-Service-help.xml. Returning to the help file, I’ll click the icon to add an example.

I think you should leave the Title alone. The same is probably true for the Introduction unless you want to demonstrate your command using a different location. The command should be your PowerShell expression. Use Remarks to display any results and commentary. I think all commands should have at least one example. Repeat as necessary.
I typically include links in my comment-based help, and you can easily do the same in the PowerShell Help Writer.
Including a related link in our 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)

The same is true if you want to define a Note, which is generally where I put version and information.
Defining a note in SAPIEN PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)
Defining a note in SAPIEN PowerShell Help Writer 2015. (Image Credit: Jeff Hicks)

Please be aware that I am testing version 1.0.9, which has a bug if you define a note and save the file. SAPIEN reports it will be addressed in the next service release. For now, I can live without it and this only affects help files created from scratch as I have been doing.
If you want to see why this is such a great tool, click the button to edit the file as XML.
Option to edit the file as XML 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)

Would you have wanted to create that file from scratch? I know I wouldn’t. If you want to fine tune the XML go right ahead, but I’m going to test the file.
The first thing to do is copy the help XML file to the same directory as my script file. If you plan on localizing your help files, you can put the file in a culture specific subfolder. Although I probably won’t localize it, I’m actually going to put the file in the EN-US subfolder. In my script file, I can remove the comment based help block and insert this instead.

​# .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.

​. c:\scripts\test-service.ps1
help test-service -showwindow

Test-Service Help. (Image Credit: Jeff Hicks)
Test-Service Help. (Image Credit: Jeff Hicks)

Now, it may be a small thing, but using an XML file fixes a few nagging issues with comment-based help. With comment-based help, there is no way to indicate if a parameter can accept a wildcard short of adding something in the parameter description. MAML format, however, can display that information.
When you create external help from a module, it gets even better, where the application will display all modules. I’ll select one of my own.

I’ll export the help to my module folder.
Exporting the help file to a module folder. (Image Credit: Jeff Hicks)
Exporting the help file to a module folder. (Image Credit: Jeff Hicks)

Now for the awesome sauce. PowerShell Help Writer goes through help for all of the functions and generates complete MAML help, including parameter sets.
PowerShell Help Writer generates complete MAML help, including parameter sets. (Image Credit: Jeff Hicks)
PowerShell Help Writer generates complete MAML help, including parameter sets. (Image Credit: Jeff Hicks)

I can go through and edit as necessary and save the file. One thing I realized after completing all the help is that the default file name included the .psm1 extension when the file name should be JH-Weather-help.xml. So I renamed the file after exiting the application. The only I have to do to my module file and functions is to delete the existing comment-based help. I don’t have to specify the new XML file. As long as it is in the same folder, PowerShell will find it and use it.

This is going to be a great asset for PowerShell professionals looking to create complete help documentation. And knowing the people at SAPIEN, I know it will get even better, but don’t take my word for it. Download a fully-functioning, 45-day evaluation, and see for yourself. If you have issues or suggestions, I encourage you to post in the product support forums at SAPIEN. I’d also like to know what you think so please feel free to leave a comment.