Writing help for custom DSC resources

Desired State Configuration is the hottest thing out there and everyone is writing custom DSC resources for almost everything. One of the most important aspects of writing custom DSC resources is to write help content on how to use these custom resources. All of us know that custom DSC resources are nothing but PowerShell modules. But, these modules contain a similar set of functions. These functions are Get-TargetResource, Set-TargetResource, and Test-TargetResource. So, writing comment-based help for these functions does not really make sense. More over, these functions are the back end mechanism for performing configuration changes. The real help that is required for a custom DSC resource should be about how to use the declarative syntax of the resource.

The way this can be solved is by using conceptual help topics or the about topic text files. The about help topics are one of the different methods of writing module help in PowerShell.

Let’s look at an example. One of the DSC resources I’d written was the HostsFile resource. I had written the about topic for this module and here is the folder structure for this DSC resource.

If you look at the folder structure and file names, you will see that I have localized the help content. For example, I have written only the English help content. So, I’d created a folder named en-US which is the UI culture on my system. Under this folder, I placed the help content for the HostsFile resource as an about text file and named it about_DSCResource_hostsfile.help.txt_. Make a note of the naming convention used. It is mandatory that the file name must end with .help.txt. I recommend that you use the naming convention that makes it easy to identify the DSC resource help content. For example, I am using about_DSCResource_.help.txt. Also, remember that the file must be saved using UTF-8 encoding.

Once you have the above criteria met, you can simply look at the about help content using the command Get-Help about*_.

Here is the partial content of my about_ text file for HostsFile DSC resource.

By following this approach, you should be able to add help content on how to use your custom DSC resources.