Awesome Reviewers expert instructions

domains / cloud-infra / Azure/azure-powershell

Documentation Source And Tone

When updating documentation (assembly metadata, cmdlet HelpMessage, generated stubs, etc.), ensure (1) you change the correct source of truth and (2) the text is written for users, not for internal implementation.

raw .md Documentation C# updated

When updating documentation (assembly metadata, cmdlet HelpMessage, generated stubs, etc.), ensure (1) you change the correct source of truth and (2) the text is written for users, not for internal implementation.

  • Do not manually edit files that are generated during build (e.g., doc/help/example/test stubs). Instead, update the autorest/custom source inputs/config so regenerated outputs are correct.
  • In public help/API documentation, describe the observable behavior, not internal transport details (e.g., avoid mentioning the underlying HTTP method like “POST”).

Example (cmdlet HelpMessage):

[Parameter(Mandatory = false,
    HelpMessage = "If specified, retrieves the WhatIf result with resource property changes populated.")]
public SwitchParameter WithPropertyChanges { get; set; }

If you need to adjust wording for generated artifacts, update the generation inputs (autorest custom folder/README configuration) rather than the generated output files, so the next build doesn’t undo your changes.

Source discussions