Since installing PowerShell 5.0, I've been using the PowerShellGet cmdlets to install and examine many of the new modules on PowerShell Gallery.
Unfortunately, this is often quite a chore. While many have some help for cmdlets, few have an About topic that tells me how to use the cmdlets together to solve real-world problems. And, in those that do, the About topic feels like the authors wrote whatever popped into their minds at the time.
In this article, I'll share my ideas for best practices for writing the primary About_Help topic for your module.
If you don't have time to read the whole article, here's a summary of the most important points. (#TL;DR)
About Help explains how the cmdlets in the module work together to perform tasks or solve problems.
We write cmdlet help for the same reason that we script: efficiency. When you invest an hour or two writing help, everyone who uses your commands, including busy IT pros on deadline, is saved the time it takes to delve in to figure out the intent and operation of your cmdlets. If it sounds familiar, it's the same rationale that we use for automation.
But, after writing cmdlet help, why do we write an About help topic for the module?
As the module author, you become so familiar with the commands in the module that their use appears self-evident. But it is likely to be far less evident to your users.
When a user runs "Get-Command -Module <ModuleName>," they get a list of exported commands in alphabetical order. But, it doesn't tell them which commands they are supposed to use, in which order, to solve the problem or perform the task that your module is designed to enable.
Which commands do you use first? Which commands are prerequisites for others? Which commands set up the environment? Which commands create objects for parameter values of other commands? Which commands pipe to each other?
That's the role of the About topic. In the words of Windows PowerShell MVP Chrissy LeMaire (@cl), "The About topic tells the story of your module."
The About topic includes information that would be inappropriate in any individual cmdlet help topic. It explains the bigger picture and provides essential guidance in using your module.
Without it, the module is a confusing collection of unrelated commands.
About Help topics are text files that have the following name format:
The "a" in "about" is lower case. The topic name is camel-cased, that is, the first letter of each word in a compound word is capitalized, like about_PSScheduledJob.help.txt or about_BitsCmdlets.help.txt.
In the primary About topic for a module, the topic name is the module name. Users learn to look for these About topics and they're delighted (and relieved!) when they find them. It's a big time-saver.
The content of the text file is technically arbitrary. Get-Help will spill out to the console whatever content is in the file.
However, there is a best-practice format, shown in this image, and in about_Topic_Template.help.txt. This format is expected by cmdlets and other tools that use and display and process the help files for other uses.
If your About topic does not conform to the expected format, it will not display properly. For example, if the short description in the About topic is not on line 5, beginning at column five, "Get-Help About*" does not display it correctly.
Also, if, in the future, PowerShell supports a serialized format for About topics (this has been "on the list" since PowerShell 2.0), the conversion tools will expect this format. If yours is not correctly formatted, it won't work.
The short description is a summary of the long description, so I usually write it after the long description is complete. Otherwise, there's nothing to summarize.
Guidelines for the Short Description:
For example, I rewrote the short description for the About_Pester help topic. The original description is incomplete (Pester does far more than just run tests) and it includes 'BDD', which is an unfamiliar term to many of us, without a description.
Pester is a BDD based test runner for Pester
Pester is a test framework for Windows PowerShell. Use the Pester language
and its commands to write and run tests that verify that your scripts and
modules work as designed.
Pester 3.4.0 supports Windows PowerShell 2.0 and greater.
The Long Description in an About topic for a module explains the tasks that the cmdlets in the module are designed to perform and the problems that their designed to solve. It explains how you use the cmdlets together in a logical sequence.
Because the About topic describes using cmdlets together, the content of an About topic is like meta-cmdlet-help; it wouldn't fit in any one cmdlet help topic.
Among the issues you might cover are:
Here are the steps I use to write an About topic:
HINT: If topic content repeatedly refers to topics below it, the topic might be out of order.
Here's a general Long Description topic outline that I use frequently:
Use examples liberally throughout the topic. Include lots of examples. They're required for inductive learners and helpful to everyone.
For example, here's the outline I used for the long description in the about_Pester topic:
You can read the current About_Pester topic here: about_Pester on GitHub
There are several optional sections of an About help topic.