Enable getting help in the terminal for DSC Resources

[michaeltlombardi]

As a user of DSC Resources, I want to be able to quickly review high level help information about them from the terminal and I especially want to be able to navigate to their online help if it exists.

Right now, at best, maintainers produce an about topic for the module their DSC Resources are in and topics for one or more resources. The DSC Community has had to build a lot of custom automation and bespoke practices around documenting DSC Resources but they're not necessarily discoverable if you don't know what you're looking for. Further, those documents are only available online, not in the terminal.

Despite the Category parameter of Get-Help supporting the values Class and DscResource (though not Enum), there doesn't seem to be a way to author this help or retrieve it.

Possible Implementations

There are three broad options for approaching this, in order from highest value/hardest implementation to lowest/easiest:

1. Make Get-Help -Category DscResource return help for DSC Resources
2. Add help info to Get-DscResource
3. Create new Get-DscHelp function

1. Update Get-Help

This option requires updating the PowerShell Help subsystem to recognize and handle DSC Resources. While it would be the most idiomatic, discoverable, and functional option, the intricacies of modifying the help system at this time may not support it.

2. Add help info to Get-DscResource

This option requires updating the DscResourceInfo type defined in the PSDesiredStateConfiguration module. As this would be adding properties to that object, it should be backwards compatible. This would keep the most useful help information with the DSC Resource's in-memory representation and be useful for numerous scenarios, including vendor integrations. However, the presentation of the information in this implementation would need careful consideration and special handling to polish the DevX.

3. Create new Get-DscHelp function

This option would require the development of a new function in the PSDesiredStateConfiguration module to handle retrieving the help information for a DSC Resource. This would be backwards compatible and retain full control over the presentation without introducing (too much) additional complexity. Combined with adding help info to Get-DscResource, this function would provide as functional and delightful a DevX as I believe possible without modifying the PowerShell Help subsystem as described in option 1.

Proposal

I propose that option one (update Get-Help to properly support DSC Resources) be implemented to ensure the best experience for module authors and users alike. Further, I propose that the same work be done for classes and enums (and, if #83 is implemented, interfaces).