Accelerating Your PowerShell Help Documentation

If you are creating PowerShell modules, I hope you are creating external help documentation. The easiest way to do this is with the platyPS module which you can install from the PowerShell Gallery. I know I have written about this module before. It is a simple two-step process. Create an intermediary set of markdown documents and then generate an external help file in the MAML format. The most time-consuming part of this process is writing the markdown files. Or to be more accurate, the most time-consuming part is editing the markdown files. Creating the markdown files is as easy as this:

Import-Module PSHelpDesk
New-MarkdownHelp -Module PSHelpDesk -OutputFolder .\docs -force

This will generate a new markdown file for every module command.

All you have to do is fill in the blanks and ideally clean up the markdown. As you can see in Figure 1 the document makes it clear what you need to fill in. Everything else is taken care of for you.

If your command has comment-based help, the markdown document will inherit that information. Otherwise, you have some work to do. However, I may have something that will help you accelerate this process. This grew out of something I tried while working on a new module recently. Opening each file, and navigating to the sections that need editing is time-consuming and tedious. You have to write something sometime, right? Who says it has to be in the markdown document?

Let me explain.

My idea is to create a JSON file that contains the help information for each command. This file can be used to edit the markdown files. Here is an example of what the JSON file might look like for a given command:

  {
    "Name": "Get-DiskInfo",
    "Synopsis": "Get disk data.",
    "Description": "Use this command to detailed disk information including usage and free space. You can specify a single drive by letter or get all fixed logical disks. \n\nThis is a new line of the description.",
    "Parameters": [
      {
        "ParameterName": "all",
        "HelpMessage": "Get details on all fixed, logical disks"
      }
    ],
    "Related": [
      "Get-BiosInfo",
      "Get-SystemStatus"
    ]
  }

These are the items I typically need to edit in new markdown help files. My concept is to generate the raw markdown files, and then edit each file using data from the JSON file. Instead of manually editing files, once I have the JSON file, I run my script and within practically no time, my markdown files are 90% complete.

Create the JSON Data File

As long as the JSON file uses the format I showed above, it doesn't matter how you create it. You could type it all out manually. Or use this script. You must import the module into your PowerShell session before running the script.