Updated external help for Microsoft.Compute

[chelnak]

Description

After submitting #3596 it was clear that the external help file had to be updated.

Contribution guidelines and this tweet confirm that New-ExternalHelp needs to be executed after we update cmdlets or the markdown files. However, the diff shows that there are significant changes were introduced after updating the external help.

This PR submits those changes for review.

More information

It looks like there are inconsistencies between markdown and external help for other services as well. For example, if i run New-ExternalHelp on the Websites module, aside from receiving a few errors caused by invalid markdown, the diff shows many differences again.

Should documentation PRs only be merged if they contain updated markdown and XML help?

Thanks guys!

---

This checklist is used to make sure that common guidelines for a pull request are followed. You can find a more complete discussion of PowerShell cmdlet best practices here.

• I have read the contribution guidelines.
• If changes were made to any cmdlet, the XML help was regenerated using the platyPSHelp module.
• If any large changes are made to a service, they are reflected in the respective change log.

General Guidelines

• Title of the pull request is clear and informative.
• There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.
• The pull request does not introduce breaking changes (unless a major version change occurs in the assembly and module).

Testing Guidelines

• Pull request includes test coverage for the included changes.
• PowerShell scripts used in tests should do any necessary setup as part of the test or suite setup, and should not use hard-coded values for locations or existing resources.

Cmdlet Signature Guidelines

• New cmdlets that make changes or have side effects should implement ShouldProcess and have SupportShouldProcess=true specified in the cmdlet attribute. You can find more information on ShouldProcess here.
• Cmdlet specifies OutputType attribute if any output is produced - if the cmdlet produces no output, it should implement a PassThru parameter.

Cmdlet Parameter Guidelines

• Parameter types should not expose types from the management library - complex parameter types should be defined in the module.
• Complex parameter types are discouraged - a parameter type should be simple types as often as possible. If complex types are used, they should be shallow and easily creatable from a constructor or another cmdlet.
• Cmdlet parameter sets should be mutually exclusive - each parameter set must have at least one mandatory parameter not in other parameter sets.

[msftclas]

@chelnak,
Thanks for your contribution.
To ensure that the project team has proper rights to use your work, please complete the Contribution License Agreement at https://cla.microsoft.com.

It will cover your contributions to all Microsoft-managed open source projects.
Thanks,
Microsoft Pull Request Bot

[msftclas]

@chelnak, thanks for signing the contribution license agreement. We will now validate the agreement and then the pull request.

Thanks, Microsoft Pull Request Bot

[cormacpayne]

@chelnak Hey Craig, thanks for the contribution!

One quick comment: instead of using New-ExternalHelp to generate the XML help, would you mind using Update-ServiceMarkdownHelp from the platyPSHelp module we have created? This cmdlet adds additional spacing between examples that is not provided when using New-ExternalHelp. This shouldn't change anything other than the reverted the changes made to the <maml:para></maml:para> tags.

Alternatively, in the platyPSHelp.psm1 script, there is a function New-ServiceExternalHelp that you can export and use to generate the XML help with appropriate spacing between examples.

Please let me know if you have any other questions!

[cormacpayne]

@chelnak Hey Craig, quick update: I'm currently working on a pull request (#3655) that will get rid of all of the XML help in this repository. This will move our partners and external contributors to update the markdown help from now on (and the XML help will be generated during the build).

As a result, I'm going to close this PR (since the file you are changing will no longer exists 😄), but I believe that once PR #3655 is merged, the changes you made previously in PR #3596 will be included in the XML help generated during build. Please let me know if you have any other questions!

[chelnak]

This is awesome thanks! It will make life much easier when updating the help!

…

On Thu, 23 Mar 2017, 16:58 Cormac McCarthy, ***@***.***> wrote: Closed #3624 <#3624>. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#3624 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ADmkJq5Qm_27RljRzKwwJeC3XCN8tIJpks5roqS-gaJpZM4McON2> .

[jonathanmedd]

Yeah, great to hear that :-)