Don Jones Month of Lunches Day 3

Original article located at: http://powershell.com/cs/blogs/donjones/archive/2012/03/05/will-day-3.aspx

As I have worked further into Powershell I have realized: Id be a millionaire if Id gotten a nickel for every time reading the help would have saved me grief.  Though Don calls it a soap box I absolutely 100% agree with section 3.1.  To make it a little shorter and more direct Ill paraphrase Steve Ballmers developer chant, “Read the help! Read the help! Read the help!” Before you hit Google.  Read the help.  Before you hit the forums.  Read the help.  After you hit the forums (and probably have an answer).  Read the help.  I am being redundant to drive home the point: Powershell tells you a lot about itself if you just listen.  So, if you want to know whats up....you know where Im going with this one.

Enough grandstanding there.  Once you get to the point of reading the help there are some things that are important to get past.  The syntax can be a little weird at first.  When I start looking for something I always use Get-Help.  My next step is invariable to use the -Full or -Examples parameters.  If the cmdlet is totally new I study the parameters, parameter sets and the arguments (paying attention to whats required-or mandatory in Powershell parlance).  Next, I look at a few examples. Now, I have to say, I have found a fair share of typos and mismatches in the help.  With version 3 there will be updating help. So, if you find an error, open a Microsoft Connect case on the issue, and, in a few days, if they fix it, run Update-Help.

Like Don pointed out, a quick tip, to help narrow down (or expand) what to search Help for, is to use wildcarding.  If you want to look at all the help for event cmdlets, use Get-Help *event*.  This often returns more information than you can practically use, but, it does help you get an idea of whats out there.  When you do find what you want, instead of having to scroll through the parameters, as I noted above, to find that one thing youre after, you can just look at the syntax.  The brackets around parameters (and arguments) tell you right away whats mandatory and whats not.  This is a good sanity check when you need to verify whether that cmdlet you are about to use does or does not need that one parameter you never seem to remember.

There are five default pieces of information provided on all parameters for a reason: they are important. When you see those five lines--Required?, Position?, Default value, Accept pipeline input? and Accept wildcard input?--pay attention.  After a while you can scan them and answer your own questions at an instantaneous glance.  However, if this is foreign to you, get you head around it now.  It will save you a lot of heart ache.  Stop.  Take a few minutes, and, read through them getting familiar with what they are saying.

One thing I would like to note is the use of Related Links.  These are links (http) or references to other help topics (built-in) that directly relate to the help you are reading.  For instance, Get-Help shows the following for related links: Online Version: http://go.microsoft.com/fwlink/?LinkID=113316, Get-Command, Get-Member, Get-PSDrive, about_Command_Syntax, about_Comment_Based_Help, about_Parameters.  So, if you want to know where to go from wherever you are at these are topics Microsoft recommends you look at next.  Be careful with third-party help.  Sometimes the documentation (read that to mean help) is not very well thought out.  On occasion I may not even be there.

A practical I would offer is to not get caught up in reading all the help.  There are some topics that can be pretty obscure, some that can be pretty rarely used, and, some that can be pretty deep.  In other words, focus your attention on the things you are working on.  There are times this will fail you because it would be great knowing about some buried features earlier on. Hopefully, however, the web and forums will get you in the ballpark and Help will get you home.  But, focusing on something like Trace-Command when you do not know how to use Get-ChildItem is putting the cart before the horse.

Great advice in that last paragraph: Focus on getting the job done. Some folks get so enthralled with chasing down every little nook and cranny in the shell that they forget its a tool for accomplishing things! Focusing on learning what you need, right then, will help move you along bit by bit.