PowerShell Version 3 Updatable Help Content

PowerShell has always had good in-box help. Each cmdlet has extensive documentation, complete with syntax and parameter details and plenty of good examples. As with all documentation, updating the help content has not been easy – or as easy as you might imagine.

With the decision to move PowerShell inside Windows, the help text has become almost read-only. If you think about the relative importance of changing help text post release, updates are not critical, so they don’t go out as part of the monthly update cycle. They don’t meet the bar for a Service Pack either. The bottom line for V2 in-box help text is that it’s effectively frozen till Win8 ships. The PowerShell team have partly worked around this by updating the on-line help, and giving the Get-Help cmdlet the ability to display, nearly seamlessly, the on-line help (i.e. use the –Online parameter to Get-Help).

For Version 3, PowerShell has updateable help content. To update your help text, you just type Update-Help and the cmdlet goes on-line and pulls down help not only for the core PowerShell cmdlets, but also for any module you have loaded on your system! That’s really cool!! This ships today with the new Version 3 update for earlier OSs and the new Win8 client/server beta.

As with many great features, there come some provisos and gotcha:

• Help content is not installed by default. When you implement the MSU to add PowerShell 3 CTP to your older system or when you load Windows 8, there is only a bare skeleton of help information available. Much of this tells you to update your help. This decision is not going to change – you have to run Update-Help to update help. Microsoft may, I understand, consider doing some things via say Group Policy, but that’s not been confirmed.
• UI Locale matters to Update-Help. Update-Help will look for help contents in the same language as your current locale. This is a problem for the Win8 beta since the number of languages supported by the beta is limited. I want en-GB content, based on my current locale, but there is none. There is, en-us, so I must specify explicitly the UI culture of the help I want to download.
• You need admin rights to run Update-Help successfully. So use an elevated PowerShell prompt.
• You need Internet access to get to the help information. You can, however, get the help content from the internet, place it somewhere, then use the –SourcePath or the –LIteralPath parameters to tell Update-Help where to find the Help source information.
• Update-Help provides minimal output by default. Use the –Verbose parameter to Update-Help to see more of what’s going on.
• Update-Help limits usage to once a day. By default, you cant’ update help more than once per day. This is to minimise the load on the MS servers providing this information. You and force Update-Help to run by specifing the –Force parameter to Update-Help.

WIth all this said here’s what Update-Help looks like on my system:

Before…

Updating Help:

And after…

In summary. PowerShell has updatable help and will use it moving forward. There are some small tricks to making it work for you, especially during the Win8 beta phase. But it’s a great feature and I love it already.

Technorati Tags: PowerShell,PowerShell V3,Windows 8,Help,Updable Help