diff --git a/docs-conceptual/azps-13.4.0/contribute-reference-docs.md b/docs-conceptual/azps-13.4.0/contribute-reference-docs.md new file mode 100644 index 0000000000..c4113dfd2e --- /dev/null +++ b/docs-conceptual/azps-13.4.0/contribute-reference-docs.md @@ -0,0 +1,64 @@ +--- +title: How to contribute to Azure PowerShell reference documentation +description: Learn how Azure PowerShell reference documentation is generated, where to contribute, and how to update published versions. +ms.topic: conceptual +ms.service: azure-powershell +ms.devlang: powershell +ms.custom: devx-track-azurepowershell +--- + +# How to contribute to Azure PowerShell reference documentation + +Understanding how Azure PowerShell reference documentation is generated and maintained ensures your +updates are applied correctly and persist across versions. + +## What is reference documentation? + +Azure PowerShell reference documentation is versioned and autogenerated for each cmdlet in the +**Az** PowerShell module. It includes: + +- Syntax and parameters +- Usage examples +- Output descriptions + +Docs are generated from the source code and are published once per module version. + +> [!IMPORTANT] +> Changes to the source repo only apply to future versions. Previously published versions must be +> updated manually. + +## How reference docs are generated + +Each Azure PowerShell submodule contains source code that defines the behavior and structure of its +cmdlets. From this codebase: + +- A **Markdown help file** is generated per cmdlet, for example, + `Update-AzVirtualHubVnetConnection.md` +- These files live in the [azure-powershell GitHub repo](https://github.com/Azure/azure-powershell) +- Markdown files are **overwritten** when a developer rebuilds or updates the module + +If you're contributing, update both: + +1. The Markdown file (for visibility in the repo) +1. The cmdlet's source code (to ensure your change persists in future releases) + +## How reference docs are published + +When a new version of **Az** PowerShell module is released: + +- A CI process creates a pull request in the + [azure-docs-powershell](https://github.com/MicrosoftDocs/azure-docs-powershell) GitHub repo +- This PR adds generated Markdown files for that version, for example, `azps-13.4.0/Az.Network/` +- This process runs **once per version**. The Markdown files are **not updated again** automatically + +## How to update existing versions + +To fix or improve docs for a previously published version: + +1. Navigate to the appropriate version folder in this repo, for example `azps-13.4.0/Az.Network/` +1. Edit the Markdown file directly +1. Submit a PR for review + +> [!NOTE] +> Reference documentation is versioned and static at publish time. Manual edits are the only way to +> update content for already-published versions. diff --git a/docs-conceptual/azps-13.4.0/toc.yml b/docs-conceptual/azps-13.4.0/toc.yml index 7355a52897..1ada658977 100644 --- a/docs-conceptual/azps-13.4.0/toc.yml +++ b/docs-conceptual/azps-13.4.0/toc.yml @@ -192,6 +192,8 @@ items: items: - name: Azure PowerShell docs style guide href: azps-docs-style-guide.md + - name: Contribute to reference docs + href: contribute-reference-docs.md - name: Troubleshooting href: troubleshooting.md - name: Frequently asked questions