How strict are approved verb semantics?

[aguzev]

Is verb semantics extension preferred over introduction of a new verb?

For example, the Approved Verbs for PowerShell Commands clearly states that Show verb is paired with Hide. As for my understanding, 'paired' means it is an antonym to Hide. The understanding might be wrong, of course, but this is a feature of the example, not the question.

At the same time we have Show-Command which displays a GUI, gets user input, and generates command text. I was not able to invent anything for a Hide-Command counterpart, which was an opposite or reverse to Show-Command.

According to the Approved Verbs page, Hide-Command should hide a command from the user, while Show-Command should unhide a hidden command.

So, the question is: should authors use an approved verb if its meaning fits the cmdlet functionality at least in English?

P.S. "Cmdlet naming is specific and constrained to allow Admins to successfully make a set of guesses about the world" Jeffrey Snover

[SeeminglyScience]

It's paired with Hide, but not necessarily required to be implemented alongside Hide. It's real nice when you can, but often you can't and that's totally fine.

According to the Approved Verbs page, Hide-Command should hide a command from the user, while Show-Command should unhide a hidden command.

So, the question is: should authors use an approved verb if its meaning fits the cmdlet functionality at least in English?

The relevant description I see is "Makes a resource visible to the user.". It doesn't really dictate that the resource should have existed previously or not otherwise be visible. That said, the only strict requirement is that the verb is in the approved list. Generally you want to just do a quick pass and try to pick the one that fits the closest. It definitely won't always be perfect, but stretching it a bit is always preferred to not picking from the list.

[aguzev]

There are Hide-VirtualDisk and Show-VirtualDisk. Does it mean that it is prohibited to create another Show-VirtualDisk with the meaning similar to Show-Command? If it is allowed, what verb should this new cmdlet use?

[aguzev]

I believe, the set of verbs had been restricted to prevent usage of multiple words for the same entity. One word for one action is consistency, which improves user experience. But with Show we see the balance moving to the opposite extreme: one word for multiple essentially different actions. What should the user expect from Show-VirtualDisk command?

If anyone asked my opinion, I am for Unhide to be approved and paired with Hide. There is a good number of Show-* cmdlets similar to Show-Command already.

[SeeminglyScience]

There are Hide-VirtualDisk and Show-VirtualDisk. Does it mean that it is prohibited to create another Show-VirtualDisk with the meaning similar to Show-Command? If it is allowed, what verb should this new cmdlet use?

Well two commands with the same name but different functionality leads to issues in command resolution, but that's about it. You'd probably just name it Show-VirtualDiskUI or something like that.

I believe, the set of verbs had been restricted to prevent usage of multiple words for the same entity. One word for one action is consistency, which improves user experience. But with Show we see the balance moving to the opposite extreme: one word for multiple essentially different actions. What should the user expect from Show-VirtualDisk command?

If anyone asked my opinion, I am for Unhide to be approved and paired with Hide. There is a good number of Show-* cmdlets similar to Show-Command already.

I think you might be putting a little bit too much stock into the recommendations. The only way they could exactly describe their specific use case 100% of the time is if they were more than one word. Otherwise you end up with synonyms you can only distinguish between with the help of documentation.

Tbh most folks don't even read the documentation for verb usage. Hell, some of them don't 100% make sense (Search for instance). Just pick the closest fit of the approved verbs and that's good enough

[aguzev]

Tbh most folks don't even read the documentation for verb usage. Hell, some of them don't 100% make sense (Search for instance).

Exactly. That is why Show-Command and Show-VirtualDisk should do similar things.

The choice of Show as pair for Hide in *-VirtualDisk commands was a mistake.

[aguzev]

"Cmdlet naming is specific and constrained to allow Admins to successfully make a set of guesses about the world" Jeffrey Snover

[kilasuit]

Just to add to what @SeeminglyScience has meantioned

Is verb semantics extension preferred over introduction of a new verb?

In most cases yes, though we will accept new verbs when they make sense & the community have asked for them where they do not

So, the question is: should authors use an approved verb if its meaning fits the cmdlet functionality at least in English?

Ideally yes

Hope this helps!

[aguzev]

I hope, the confusion between Show-Command and Show-VirtualDisk illustrates my point enough. As well as their pairs Hide-VirtualDisk and Hide-Command. The latter isn't even provided out of the box. Multiple meanings for a single symbol do not improve UX.

What about Get-Prepared for environment initialization? To my ear, it is a terrible cmdlet name while still sounds good in English.

At the same time there are Find and Search, Invoke and Start, which are explicitly indicated as synonyms to avoid for each other. There is a need to explain their differences. Following this logic, Reveal or Expose look like better pairs for Hide, e.g. Show-Command, Expose-VirtualDisk.