Chapter 3: Using the help system

Introduction

Introduces PowerShell’s help system as a discoverability feature that makes its commands easier to learn.

• PowerShell help and discoverability: Explain why PowerShell’s help system matters for discovering commands, despite command-line interfaces seeming less discoverable than graphical interfaces.
  Why it matters: The help system gives you a way to explore PowerShell instead of relying on visible menus.

Key terms: discoverability, help system, command-line interfaces (CLIs), graphical user interfaces (GUIs)

3.1 The help system: How you discover commands

This section explains why reading PowerShell help is essential for discovering commands and learning to use them, and clarifies what the book means by “command.”

• Help as first resource: Explain why the built-in help system should be the first place to look when learning PowerShell, rather than relying on GUI-style discovery or a search engine.
  Why it matters: Treating help as a starting point lets you work out unfamiliar tasks instead of depending on someone else’s example.
• Help for command use: Describe the kinds of questions the help system can answer when you need to find, run, or combine commands, and why the book’s examples are not a substitute for it.
  Why it matters: These uses of help let you discover syntax and capabilities beyond the examples shown in the book.
• Commands and cmdlets: Distinguish the section’s general use of “command” from the more specific term “cmdlet.”
  Why it matters: This distinction prevents you from assuming that help applies only to cmdlets.

Key terms: help system, help files, GUI discoverability tools, command, syntax, options, cmdlet, function

3.2 Updatable help

This section explains why PowerShell help may initially be sparse and how to update it, including on computers without internet access.

• Initial and updated help: Explain why help for a command may initially be abbreviated and how to obtain fuller help with Update-Help.
  Why it matters: Updating help gives you more useful command documentation than the initial autogenerated version.
• Help maintenance and availability: Describe when to refresh help and the conditions under which non-Microsoft command help can be updated.
  Why it matters: Regular updates help keep command documentation current, including documentation for eligible third-party commands.
• Offline help distribution: Describe how to make updated help available to computers that cannot reach the internet.
  Why it matters: Computers without internet access can still receive updated help from a shared local source.

Key terms: updatable help, Update-Help, modules, Save-Help, -Source

3.3 Asking for help

This section shows how to ask PowerShell for help, why Help displays it differently from Get-Help, and what the help system is for.

• Get-Help and Help behavior: Distinguish Get-Help from Help when requesting help for a command, including how Help displays long output and how to leave that display.
  Why it matters: You can choose a readable help display without mistaking Help for a separate help system.
• Help system purposes: Explain the two tasks PowerShell’s help system is meant to support.
  Why it matters: Help is useful both before you know which command you need and after you have found one.

Key terms: Get-Help, Help, function, less, help system, commands

3.4 Using help to find commands

This section shows how to discover PowerShell commands through help-topic searches and, alternatively, through Get-Command.

• Help Topics Versus Commands: Explain that Help searches available help topics rather than the commands present in the shell, so a command without a help file may not appear in a Help search.
  Why it matters: This distinction explains why Help is useful for discovery but is not a guaranteed inventory of commands.
• Wildcard Help Searches: Describe how to search for possible commands by giving Get-Help or Help a broad, wildcard-containing topic name, then request help for a promising specific command.
  Why it matters: A broad search helps you find candidate commands when you do not yet know their names.
• Command Completion And Summary Help: Describe how tab completion helps explore command-name matches and what the summary help shown for a command is for.
  Why it matters: These shortcuts help you move from possible command names to a quick reminder of how a chosen command is used.
• Direct Get-Command Searches: Distinguish Get-Command searches from Help searches and describe how its wildcard, -Noun, -Verb, or command-type options narrow the results.
  Why it matters: Searching commands directly offers another way to discover cmdlets without relying solely on help topics.

Key terms: Help, help topics, cmdlets, Get-Help, -Name, wildcards, * wildcard, tab completion, summary help, syntax

3.5 Interpreting the help

This section explains why learning the conventions of cmdlet help makes the help files more useful.

• Cmdlet help conventions: Explain why understanding the conventions in PowerShell cmdlet help files helps you use the files and the cmdlets more effectively.
  Why it matters: Reading help effectively makes it easier to teach yourself how to use a cmdlet.

Key terms: cmdlet help files, conventions

3.5.1 Parameter sets and common parameters

This section explains how to read multiple parameter sets in cmdlet help and what the CommonParameters notation means.

• Parameter sets and compatibility: Explain how repeated command syntax identifies parameter sets, how shared and unique parameters distinguish them, and why choosing a unique parameter restricts which other parameters can be used.
  Why it matters: Parameter sets help you tell which combinations of parameters form a valid command.
• Shared parameters and common notation: Describe what happens when a command uses only parameters shared by multiple sets, and explain what [<CommonParameters>] at the end of cmdlet syntax signifies.
  Why it matters: These details help you interpret syntax that fits more than one set and recognize parameters available across cmdlets.

Key terms: parameter sets, -Path, -LiteralPath, -Filter, mutually exclusive, shared parameters, first-listed parameter set, [<CommonParameters>], common parameters

3.5.2 Optional and mandatory parameters

This section shows how help marks optional and mandatory parameters, what happens when a required value is missing, and how to shorten parameter names safely.

• Optional and mandatory parameter notation: Explain how square brackets in PowerShell help distinguish an optional parameter from a mandatory one, using -Credential and Get-Item -Path as examples.
  Why it matters: This notation tells you which inputs a command requires before you run it.
• Missing mandatory parameter prompt: Describe what happens when Get-Item is run without its mandatory -Path parameter and how to respond to the prompt.
  Why it matters: A missing required value need not leave you guessing about why the command has not run.
• Unambiguous parameter name abbreviations: Explain when a parameter name may be shortened, using -Force and -Filter to illustrate the limit.
  Why it matters: Knowing the uniqueness rule lets you shorten names without making a command ambiguous.

Key terms: optional parameters, mandatory parameters, square brackets, Get-Item, -Path, Ctrl-C, parameter name, -Force, -Filter

3.5.3 Positional parameters

This section explains how to recognize positional parameters in PowerShell help, use them without losing track of their positions, and decide when to spell out parameter names.

• Positional parameter syntax: Explain how the syntax summary distinguishes a positional parameter from an optional parameter, using Get-Item’s -Path and -Stream as examples.
  Why it matters: Reading the brackets correctly helps you tell whether you can omit a parameter name and whether the parameter itself is required.
• Position and named arguments: Trace how PowerShell assigns values when positional and named parameters are mixed, and explain why the order of unnamed values matters.
  Why it matters: Keeping unnamed values in the right order prevents them from being assigned to the wrong parameters.
• Full help position index: Describe how to check a parameter’s position in full help and what the Get-Item -Path entry shows.
  Why it matters: Full help lets you confirm a parameter’s position while reading its description and other details.
• Readable parameter usage: Justify when to use positional shortcuts and when to write complete parameter names.
  Why it matters: Spelling out names makes saved commands easier to understand without adding repeated typing.

Key terms: positional parameters, syntax summary, -Path, -Stream, -Filter, Get-ChildItem, Help Get-Item -Full, full help, position index, parameter names

3.5.4 Parameter values

Explains how to read parameter value types in PowerShell help and supply single values, lists, prompted values, and switches.

• Parameter value syntax and types: Explain how help syntax shows the kind of value a parameter accepts and how to supply that value. Describe the String, integer, and DateTime types introduced here.
  Why it matters: Help syntax tells you what to type after a parameter name.
• Array values and quoting: Explain what String[] means and how to give such a parameter one or several values without quoting the whole list.
  Why it matters: The placement of commas and quotes determines whether PowerShell receives separate values or one string.
• Prompting for multiple values: Describe how to enter several values when PowerShell prompts for a mandatory parameter that accepts multiple values.
  Why it matters: You can respond to a mandatory parameter prompt with several values without putting them all on the command line.
• Switch parameter behavior: Distinguish a switch from a parameter that takes a value, including whether its name must be typed and what the section’s Force example changes.
  Why it matters: Recognizing a switch prevents you from supplying an unnecessary value or trying to use it positionally.

Key terms: parameter value, String, Int, Int32, Int64, DateTime, String[], array, comma-separated list, quotation marks

3.5.5 Finding command examples

This section shows how to display PowerShell command examples from help and how to read Windows-based examples on other platforms.

• Finding command help examples: Explain that PowerShell help files contain usage examples and that `Help` with `-Example` displays them when examples are all you want, instead of using `-Full`.
  Why it matters: Examples give you a quick way to see how a cmdlet is used.
• Cross-platform example paths: Explain that examples may show Windows paths, but readers on macOS or Linux can use paths for their own platform; PowerShell accepts either `/` or `\` as a directory separator.
  Why it matters: You can still use help examples when their paths look different from those on your computer.

Key terms: Help, -Example, -Full, help files, Windows paths, macOS or Linux paths, directory separator

3.6 Accessing “about” topics

This section shows how to find PowerShell’s background “about” topics through the help system.

• Finding about help topics: Explain that about topics provide background documentation rather than help for a specific cmdlet, and describe how to find them with a wildcard help search.
  Why it matters: About topics make useful documentation available even when you do not have a particular cmdlet in mind.

Key terms: about topics, about_, get-help, wildcards

3.7 Accessing online help

This section shows how to open web-based PowerShell help, why it can be useful, and how the PowerShell team’s help files can be improved.

• Online help access and value: Explain how to open online help for a command and why it can be useful when installed help appears wrong or outdated.
  Why it matters: Online help gives you another place to check a command’s documentation when the installed version seems questionable.
• Open source help contributions: Describe who can improve the PowerShell team’s help files and the limits of that documentation project.
  Why it matters: You can help fix mistakes in the PowerShell team’s documentation without assuming its project covers every product team’s commands.

Key terms: -Online, Microsoft Docs, Update-Help, open sourced, PowerShell-Docs, PowerShell team

3.8 Lab

3.9 Lab answers