Weekend Scripter: Where Is the DSC Documentation?


Summary: Microsoft Scripting Guy, Ed Wilson, talks about where to find documentation for Windows PowerShell Desired State Configuration (DSC).

Microsoft Scripting Guy, Ed Wilson, is here. One of the things that sometimes surprises me, is when I am talking to IT pros and I hear something like, “I really like Windows PowerShell, but I wish that there was more documentation about it.” This is, if you will, a “Hmmmmm” type of moment.

From where I sit, I would think that that perhaps the issue is not that there is no documentation, but that there is so much documentation, it is hard to find what one really wants or needs. Perhaps it all depends on one’s view of documentation.

Note  Stay tuned for a way cool post from the Scripting Manager about “the changing nature of documentation.”

Whenever I start looking for documentation for Windows PowerShell, the first thing I do is look at the Help files. When I am looking for something that is more of a concept than a specific cmdlet, I look for a Helpfile.

I like to use the Get-Help cmdlet, specify my category, and then specify something that will get me close to the topic I seek. Following is the command I use. (I can type this command in the Windows PowerShell console or in the execution pane of the Windows PowerShell ISE—either place works the same.)

get-help -Category HelpFile desiredstate

This command displays the about_Desired_State_Configuration topic. If I searched for DSC instead, I would still find the topic, but I would also have a few more items returned. Here is what I am talking about:

PS C:\> get-help -Category HelpFile dsc

 

Name                                    Category  Module                    Synopsis                                                  

----                                           --------  ------                           --------                                                  

about_Classes                                HelpFile           Describes how you can use classes to develop in Windows

about_Debuggers                           HelpFile           Describes the Windows PowerShell debugger.                

about_DesiredStateConfiguration   HelpFile          Provides a brief introduction to the Windows              

about_Windows_PowerShell_4.0    HelpFile           Describes new features that are included in               

about_Windows_PowerShell_5.0    HelpFile           Describes new features that are included in         

The about_Desired_State_Configuration Help topic is really pretty good, and it provides a great overview of how to create a configuration script and how to guard against configuration drift. It also lists the inbox DSC resources. But one of the best things about the Help topic is that at the bottom (and also near the top), it includes a link to the applicable TechNet Library section, Windows PowerShell Desired State Configuration. This topic, which is shown in the following image, offers good information about DSC, how to use it, and some great tips for using it in a real-world environment.

Image of webpage

These two resources are absolutely the place to get started when using Windows PowerShell DSC. They also constitute official Microsoft documentation about this feature.

Other resources for DSC documentation

There is a lot of documentation from Microsoft for Desired State Configuration in the form of blogs. The Hey, Scripting Guy! Blog, for example, has around 25 posts related to DSC. The PowerShell Team blog has nearly twice that number of posts tagged with DSC. But many of those posts are notices such as the DSC Resource Kit wave releases.

Speaking of the DSC Resource Kit wave releases, each resource module in the DSC Resource Kit includes sample scripts that illustrate how to use the resource. In addition, each resource includes documentation. The samples and sample documentation are available in each module folder.

The Microsoft Press book that I wrote, Windows PowerShell Best Practices, includes an entire chapter devoted to DSC. In that chapter, I include configuration scripts and talk about all of the standard DSC resource providers.

Channel 9 has recordings of TechEd presentation sessions about Windows PowerShell DSC. For example, there is a talk by Don Jones (A Practical Overview of Desired State Configuration) and there is a talk by Kenneth Hansen and Jeffrey Snover (Desired State Configuration in Windows PowerShell).

PowerShell.org has an entire forum devoted to Desired State Configuration, in which there are nearly 200 posts.

PowerShell Magazine has a number of very interesting articles about DSC.

There are also several videos on You Tube that talk about DSC.

So, there are lots of sources of documentation about using Windows PowerShell DSC.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy

Comments (1)

  1. Steve says:

    The need for such article should drive you to think whether microsoft is on track to tackle future challenges. I cannot recommend dsc and powershell at all due to mainly two reasons. One is the nightmare to find information about dsc and powershell language
    in particular. I never found any normative reference about powershell language at all. This is anoying and causes high effort to use it. Great that this article tries to provide guideance and that it’s providing links, but all competitors to DSC I knew of
    managed to put everything together to use it right away. Examples are good to have, but learning languages and/or framework by example is very unefficient and error prone. Please improve your documentation.

    feedback concerning the introductionary video: its completely useless as starting point. To raise attraction its really to long. 5min for that should be fully sufficient.

Skip to main content