F1 when the help isn't downloaded yet

Press F1 on Get-ChildItem in a fresh PowerShell 7 install and you run into one of the platform’s quieter awkward facts: there is almost no help on the box. PowerShell 7 ships thin auto-generated placeholders, a syntax block plus a remark pointing at Update-Help, and the full documentation only arrives after you run that download yourself. Plenty of tools render the placeholder as if it were the documentation. The user stares at a skeleton and concludes PowerShell’s help is bad.

DetentShell’s F1 works with the situation instead of around it. Put the caret on a command and press F1, or use the Help menu, or right-click, which moves the caret to the word under the mouse first so “help on that” means that word. The help panel renders whatever your session has.

When what your session has is the placeholder, the panel says so. It detects the auto-generated stub and offers two ways forward. A link to the online documentation, which is always current. And a one-time “Run Update-Help” nudge: click it, the download runs, and the panel re-renders with the full content where the skeleton was. The nudge appears once. The second time it would just be nagging.

Detecting “this is a stub” is fiddlier than it sounds, since the placeholder isn’t flagged as one. It’s help-shaped text with telltale remarks in it. We match on the rendered text’s own markers, the Update-Help pointer and the partial-help phrasing, rather than probing help-object internals that shift between engine versions.

Because help comes from your session, modules bring their documentation with them. Import dbatools and F1 on its commands shows dbatools help. Write comment-based help in your own functions and F1 honors it.

The rule the feature follows: when the answer is on the box, show it. When the answer is a download away, say that and hold the door open. Never dress a placeholder up as the real thing.

← All posts