Keeping Help Helpful: Use -Online and Redirectable Links

Keeping Help Helpful: Use -Online and Redirectable Links

Rate This
  • Comments 4

When you refer to Windows PowerShell help topics, such as in tools and blog posts, be sure to refer to the most recent version of the help topics. Few things are less helpful or more confusing than sending a reader to a topic that is missing a parameter or includes an example that doesn't work.

To be sure that you're always referring to the newest help topics, refer to the online help topics in the TechNet library.

  • In tools, use a Get-Help -Online command.
  • In web pages, use the redirectable "forwarding" links (also known as "FWLinks") to the help topics.

The redirectable links will always be current. Even if a help topic page moves or changes, the redirectable link always connects to the newest version of the help topic.

You can find redirectable links to all Windows PowerShell 2.0 core help topics in the CSV file that is attached to the following blog post: http://blogs.msdn.com/b/powershell/archive/2009/07/21/urls-for-powershell-core-help-topics.aspx

All redirectable links have the format: http://go.microsoft.com/fwlink/?LinkID=<LinkID>, where only the LinkID varies. If you see a raw URL link, such as http://technet.microsoft.com/en-us/library/dd819454.aspx, or worse, a help topic that is copied so it isn't updated, please notify the author that their topics are likely to be obsolete and point them to the redirectable links.

To make it easy to find the redirectable link to any topic, create a function that reads the CSV file and displays the redirectable link. Here's the one I use:

function get-fwlink
{
    param ([string]$title)

    $a = import-csv -path .\PowerShellHelpURLs.csv -Header Type, TopicName, URL
    $b = $a | where {$_.TopicName -like "*$title*"}
    foreach ($match in $b)
    {
        write-host ""
        $match.TopicName
        $match.URL
    }
}

PS C:\ps-test> get-fwlink keyword

about_Language_Keywords
http://go.microsoft.com/fwlink/?LinkID=136588

Even if you're getting old and obsolete, your links will always be current.

June Blender [MSFT]
Windows PowerShell Documentation
Twitter: juneb_get_help

Leave a Comment
  • Please add 2 and 2 and type the answer here:
  • Post
  • "Get-help -online" is very cool. Any plans to release updates to PowerShell's inline help and/or .CHM file between major PowerShell releases?

    I've always found .CHM format to be the easiest way for me to consume help documentation. It is fast, hyperlinked, searchable, indexed, has a table of contents and is all available offline.

    There is somewhat of a precedent for out of band releases of help documentation, for example this WSH help download:

    www.microsoft.com/.../details.aspx

  • Hi, Craig,

    The in-product help files are hard to update, because they're actually part of Windows. We've had many request for other update formats. Not so many requests for CHMs, because IT folks have security concerns. I hear you, though.

    VMM has a .doc download: www.microsoft.com/.../details.aspx. PDFs are a possibility, too.

    Thanks,

    June

    June Blender [MSFT]

    Windows PowerShell Documentation

  • There is a serious bug with powershell online help in german windows 7 SP1 and Server 2008 R2 SP1!

    If I call the help about get-help:

    get-help get-help

    It lists the german help and shows related links, like this:

    VERWANDTE LINKS

       Online version: go.microsoft.com/fwlink (möglicherwei

       se auf Englisch)

       about_Comment_Based_Help

       Get-Command

       Get-PSDrive

       Get-Member

    Now when I call:

    get-help get-help -online

    A browser windows opens with this link:

    go.microsoft.com/fwlink

    The primary link is ok, but the german annotation of "(möglicherweise auf Englisch)" gets appended and therefore the link is redirected to: search.microsoft.com

    So the powershell -online help option is useless!

    If I use copy and paste the link: go.microsoft.com/fwlink everything is fine.

  • Thanks for the report, Mike. I'm going to have our Localization Team check this out right now. The forwarding links (i.e. go.microsoft.com) are designed to work in any supported language. If they're not working, we'll fix it.

    Thanks,

    June

Page 1 of 1 (4 items)