• Windows PowerShell
• Modules
• Windows PowerShell 5.0
• Best Practice

User Rating: 5 / 5

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.

Best Practices for a Module About_Help Topics

If you don't have time to read the whole article, here's a summary of the most important points. (#TL;DR)

• Explain how the commands in the module work together to solve problems or perform tasks.
• Use clear, simple language. Avoid jargon. Don't be clever.
• Define all terms that the audience is unlikely to know.
• Short Description is a summary of the Long Description. Write it last.
  • Identify the technology.
  • List system requirements.
• Long Description:
  • Start with an outline
  • Arrange paragraphs in an order meaningful to the reader. Do not use "stream of consciousness" writing.
  • Use subtitles to label paragraphs
  • Reorder after writing.
  • Include lots of examples.
• Have a GitHub wiki? List it in the See Also section.

Why Write About Help for a Module?

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.

Mechanics of an About Help Topic

About Help topics are text files that have the following name format:

about_<TopicName>.help.txt

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.

about_<ModuleName>.help.txt

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.

What do I write in the Short Description?

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:

• 1-2 paragraphs that answer: "Will this module solve my problem?"
• What tasks can you perform
• In which domain or technology does it work?
• System requirements
• If the topic is long, list the subtitles in this section, like a table of contents.

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.

Original:

Pester is a BDD based test runner for Pester

To:

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.

What do I write in the Long Description?

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:

• Where do I start? Which commands do I use first (or even read about first)?
• In what order do I use the other commands?
• Are there implicit groups of commands (beyond nouns)?
• Is one a prerequisite for another?
• Is one designed to pipe to another?
• Examples: Lots of them (Need help? See: How to Write Great Help Examples)

Here are the steps I use to write an About topic:

1. Brain-storm topics.
2. Arrange the topics in an order that makes sense to the reader (not to you)
   • Logical order (based on prerequisites)
   • Simple - complex
   • Common - rare techniques
3. Write a paragraph or two for every topic.
4. Reorder the topics.

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:

• Purpose / Solution / Task
• Basic example
• Cmdlet/Function list
• How-to sections (New/Get/Set/Save)
• Examples (try it)
• Background info

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:

• Problem statement: Unit/integration testing
• Language basics, DSL (describe, it, should be)
• How-to: Create, Write, Run
• How to save; default output is Write-Host
• Example. Try it.
• Real-world examples (from original file)

You can read the current About_Pester topic here: about_Pester on GitHub

Other Sections of an About topic

There are several optional sections of an About help topic.

• EXAMPLES : This is a section dedicated to examples, or one or two extended examples. The examples here are an addition to the examples that you use throughout your topic. I like examples that walk me through a process step by step.
  Need help? See: How to Write Great Help Examples
• NOTE : A section for information that isn't appropriate elsewhere, including technical information, warnings, corner cases, and, rarely, implementation details.
• TROUBLESHOOTING NOTE : List workarounds for known bugs that aren't yet fixed, but might be fixed in the future. Let the user know that they shouldn't rely on this behavior because it's likely to change.
• SEE ALSO : List related topics with a URL, when appropriate. This is a great place for a link to the GitHub project or wiki, or a favorite links to any type of related content, including videos, webzine articles, and blog posts.
• KEYWORDS : Use this section to list synonyms or search terms that are relevant to the topic. We added this section to support the full-text search feature of Get-Help. While Get-Help will find all words used in the topic, you can put them here rather than trying to force them into your text.

If you have questions or need help with an About topic, ask on our Windows PowerShell forum or ping me on Twitter at @juneb_get_help or @SapienTech.

June Blender is a technology evangelist at SAPIEN Technologies, Inc. and a Windows PowerShell MVP. You can reach her at This email address is being protected from spambots. You need JavaScript enabled to view it. or follow her on Twitter at @juneb_get_help.

• Prev
• Next