A Helpful Message about HelpMessage

The Scripting Games 2013 winners have not yet been announced, but for the 3rd year running, I’m in the lead for the “Learned Most from the Scripting Games” award. I’m making space for the prize on my bookshelf. Seriously, I play with PowerShell all the time and read lots of blogs, but nothing compares to looking at dozens of scripts and commands and seeing how people do things in the real world.

One of the practices I’ve noticed is use of the HelpMessage parameter attribute to document a parameter. It’s a real thing, but I didn’t know that anyone used it any more.

Here’s my help message about HelpMessage:

Don’t use it! Users can’t see it. It does no harm, but it has no value. Danger lurks in writing a HelpMessage instead of writing help that users can see. Write help that Get-Help gets, that is, XML help or comment-based help.

Here’s what I’m talking about. This code is valid. The language permits it. But it’s not useful. And I saw it in several of the advanced solutions.

But Get-Help doesn’t get the HelpMessage string.

There are two ways for the user to see this help message. Here’s one way. These commands get the value of the HelpMessage property of the parameter. I don’t think people run commands like these very often, but I don’t get out much.

Here’s the other way. It works only on mandatory (required) parameters. When you omit a mandatory parameter, you get a message like this one:

And then you type “!?” to get the HelpMessage value.

You’ve never done that? Me neither!

To get a sense of how often HelpMessage is used, I played Nate Silver with Kim’s famous test server. My dear friend, Kim Ditto, is famous for many things — she’s a fabulous person and a renowned Microsoft Certified Trainer — but, in addition, she set up and maintains a test server on which she’s installed almost all of the Windows PowerShell modules from Microsoft. I could not live without Kim’s test server.

Here are the results. Out of 2468 commands with 8471 parameters, 8 have the HelpMessage attribute and none are mandatory, so the HelpMessage is NEVER DISPLAYED unless you go hunting for it.

If you want to be helpful, the correct way to provide help for a parameter in a script or function is this:

Or, this:

Hope that’s helpful.

About June Blender

June Blender was a senior programming writer on the Windows PowerShell team at Microsoft from Windows PowerShell 1.0 – 3.0. You see her work every time you type Get-Help for the core modules. She's now working on the Windows Azure Active Directory SDK team, and she remains an avid Windows PowerShell user and a passionate user advocate. She's a guest blogger for the Scripting Guys and she tweets Windows PowerShell tips on Twitter at @juneb_get_help. A 16-year veteran of Microsoft, June lives in magnificent Escalante, Utah, where she works remotely when she's not out hiking, canyoneering, taking Coursera classes, or convincing lost tourists to try Windows PowerShell. She believes that outstanding documentation is a collaborative effort, and she welcomes your comments and contributions to Windows PowerShell and Windows Azure Help.

One thought on “A Helpful Message about HelpMessage

  1. Pingback: PowerShell Tip #3 from the Winner of the Advanced Category in the 2013 Scripting Games | Mike F Robbins

Comments are closed.