Finding and Using Windows PowerShell Documentation

Doctor Scripto

Summary: Microsoft Scripting Guy, Ed Wilson, talks about sources of Windows PowerShell documentation.

 Hey, Scripting Guy! I like Windows PowerShell, but it does not seem to come with any documentation. What is up with this? It seems that Microsoft makes this great product, and then they did not produce any docs for how to use it. I just don’t get it.

—WB

 Hello WB,

Microsoft Scripting Guy, Ed Wilson, is here. The Scripting Wife and I are upstairs in my office. I am reading through the email sent to scripter@microsoft.com, and she is on her laptop hanging out on Twitter, Facebook, and whatever else she is up to these days. I am sipping a nice cup of Earl Gray tea with a bit of jasmine flower in it. I had some Earl Gray tea in Virginia Beach with jasmine in it, and it was really quite nice. So I looked around, and I found a place that sells organic, food-grade jasmine flowers, and I have been dying to try it out. It makes for a delightful afternoon tea.

Finding Windows PowerShell Help

WB, I must admit that my first expression was, “Dude, you have got to be kidding me.” But on reflection, I have received many emails asking about the “missing Windows PowerShell documentation.” If I think back about Windows NT 3.51, the product shipped with about a dozen floppy disks stuffed in a legal-sized envelope, about four pounds of books, and a heavy-duty cardboard box that was capable of protecting the most delicate crystal glasses during a transatlantic oceanic voyage.

Although I liked the books that shipped with Windows NT 3.51 (I especially thought the troubleshooting book was excellent), I do know people that never opened those books. In addition, by the time Windows NT Server 3.51 received its fifth service pack, the books were terribly out-of-date. One thing we have done to help with the problem of out-of-date documentation is to enable books on demand. The Scripting Manager, Dave Bishop, wrote an excellent blog called How to Print Documents from the TechNet Library and MSDN.

So, the thing to keep in mind is that product documentation is changing. These days, we have many sources of information. In all of these different areas, Microsoft employees, Microsoft MVPs, and other community leaders take an active part in creating and in developing content. A quick review of some of the different sources is listed here.

1. Video
2. Wiki
3. Library pages
4. Blogs
5. Forums
6. Quizzes
7. Script Repositories
8. Books
9. On-the-box
10. Facebook
11. Twitter
12. Windows PowerShell on the Microsoft Download Center
13. Windows PowerShell on CodePlex

The image that follows illustrates the two Windows PowerShell quizzes that are available from the Learn PowerShell page on the TechNet Script Center. The quizzes correspond to two series of videos also available from the Learn PowerShell page. The quizzes be taken multiple times, and they represent a significant learning opportunity. Each question contains links to resources that explain the concept being tested.

Last year, the Windows PowerShell language specification released. This several-hundred page document provides detailed documentation about how the Windows PowerShell language works. It is a great resource for anyone who wants to develop a deep understanding of how Windows PowerShell really works. Also last year, an update to the on-the box core Windows PowerShell Help released in the Microsoft Download Center.

The online advantage

WB, one of the huge advantages to maintaining documentation online is that producing on-the-box documentation is a static process. A group of writers, editors, and tech reviewers develop the content, and it is printed and shipped. Most of the new online documentation represents an iterative process.

For example, I write a Hey, Scripting Guy! Blog based on an email I receive. The blog is edited and published. Next, someone adds a comment that I missed something. I can immediately go back into the blog and edit it to reflect the new comment. Often this happens the same day. If you have a question about something in my book, you email the publisher. The publisher emails me. I make a revision, and forward it back to the publisher. The publisher forwards it to the printer, and in the next printing, the change takes place. This process takes months, not days. And it is a process that occurs for only the most grievous of errors.

Working locally – searching globally

The Help that is returned from inside the Windows PowerShell console is basically out-of-date. It was out-of-date when the product shipped. This is because of the lag time between when the documentation must be completed and date when the final build of the product became ready to ship. Patches, updates, service packs, and other changes conspire to continue to make the Help out-of-date. Because of this situation (which is something we knew would happen), Windows PowerShell added the online switch. This permits access to the latest Help updates at all times. The technique of using the online switch is shown here where I obtain Help about the Get-Process cmdlet from the online Microsoft TechNet Library.

Get-Help Get-Process –Online

When you execute the command, the Windows PowerShell console returns control to you. Internet Explorer opens to the appropriate page in the TechNet Library with the latest documentation for the command for which you inquired—in this case the Get-Process cmdlet.

A way cool thing to do is to combine the online Help feature with the Build-a-Book feature that the Scripting Manager described in How to Print Documents from the TechNet Library and MSDN. This technique is shown in the image that follows.

WB, that is all there is to finding and using Windows PowerShell documentation. Join me tomorrow for a guest blog by Microsoft PFE, Jason Walker, as he talks about how to retrieve USB drive usage history. You DO NOT want to miss this most excellent blog—just sayin’.

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 

Doctor Scripto Scripter, PowerShell, vbScript, BAT, CMD

Follow