UseApprovedVerbs.md: Improving Documentation #1294
Conversation
I have come to this documentation a few times in the past. Get-Verb is very helpful, but the additional insight, and examples of unapproved verbs in the Microsoft docs are very helpful and make it easier to decide on a suitable replacement for an unapproved verb. I think it would be helpful to have a link to that documentation here.
| @@ -8,6 +8,8 @@ All CMDLets must used approved verbs. | |||
|
|
|||
| Approved verbs can be found by running the command `Get-Verb`. | |||
|
|
|||
| Additional documentation on approved verbs can be found in the microsoft docs page [Approved Verbs for PowerShell Commands](https://docs.microsoft.com/en-us/powershell/developer/cmdlet/approved-verbs-for-windows-powershell-commands). If you find the verb you are using is unapproved, try searching the page for the approved equivalent. For example, if you search in the documentation for `Read`, `Open`, or `Search` you will find that the approved verb for those situations is `Get`. | |||
There was a problem hiding this comment.
Thanks. Looks good to me. Just a minor suggestion to take out the \en-us part of the link so that the page gets displayed in the user's locale.
| Additional documentation on approved verbs can be found in the microsoft docs page [Approved Verbs for PowerShell Commands](https://docs.microsoft.com/en-us/powershell/developer/cmdlet/approved-verbs-for-windows-powershell-commands). If you find the verb you are using is unapproved, try searching the page for the approved equivalent. For example, if you search in the documentation for `Read`, `Open`, or `Search` you will find that the approved verb for those situations is `Get`. | |
| Additional documentation on approved verbs can be found in the microsoft docs page [Approved Verbs for PowerShell Commands](https://docs.microsoft.com/en-us/powershell/developer/cmdlet/approved-verbs-for-windows-powershell-commands). If you find the verb you are using is unapproved, try searching the page for the approved equivalent. For example, if you search in the documentation for `Read`, `Open`, or `Search` you will find that the approved verb for those situations is `Get`. |
There was a problem hiding this comment.
Thanks for the suggestion. I have removed that. Do I need to squash both changes into one commit before the pull request is completed?
There was a problem hiding this comment.
You're welcome. No need for squashing, when the PR gets merged all commits will get squashed automatically by GitHub and the final commit message will be the PR title and the description. I will assign a 2nd reviewer to as a best practice and we'll then take care of merging it in. Thanks :-)
| @@ -8,6 +8,8 @@ All CMDLets must used approved verbs. | |||
|
|
|||
| Approved verbs can be found by running the command `Get-Verb`. | |||
|
|
|||
| Additional documentation on approved verbs can be found in the microsoft docs page [Approved Verbs for PowerShell Commands](https://docs.microsoft.com/powershell/developer/cmdlet/approved-verbs-for-windows-powershell-commands). If you find the verb you are using is unapproved, try searching the page for the approved equivalent. For example, if you search in the documentation for `Read`, `Open`, or `Search` you will find that the approved verb for those situations is `Get`. | |||
There was a problem hiding this comment.
Ideally this could be broken into semantic lines.
There was a problem hiding this comment.
The second sentence is backwards I think; it reads like:
If you are using an unapproved verb, try searching for its approved equivalent (which you're trying to find)
It might be worded better as:
Some unapproved verbs are documented on the approved verbs page and point to approved alternatives; try searching for the verb you used to find its approved form. For example, searching for
SearchorOpenwill lead you toGet.
There was a problem hiding this comment.
Good point. I'll update that.
|
Thanks for your contribution @Banner-Keith |
|
@rjmholt I noticed that the Show documentation hint in the PowerShell extension points at the development branch. That might be because I'm using the preview. Anyway. This change is not in the development branch, just in master. Could we merge it there too? |
|
@Banner-Keith After the release of |
|
@bergmeister Thanks for the reply. |
PR Summary
I have come to this documentation a few times in the past. Get-Verb is very helpful, but the additional insight, and examples of unapproved verbs in the Microsoft docs are very helpful and make it easier to decide on a suitable replacement for an unapproved verb. I think it would be helpful to have a link to that documentation here.
The contribution guidelines say "Submit your own fixes or features as a pull request but please discuss it beforehand in an issue if the change is substantial." This change is not substantial and therefore I did not open an issue first.
PR Checklist
.cs,.ps1and.psm1files have the correct copyright headerWIP:to the beginning of the title and remove the prefix when the PR is ready.