diff --git a/reference/docs-conceptual/community/contributing/quality-improvements.md b/reference/docs-conceptual/community/contributing/quality-improvements.md index ce35b60daaea..c70f0f0b56f5 100644 --- a/reference/docs-conceptual/community/contributing/quality-improvements.md +++ b/reference/docs-conceptual/community/contributing/quality-improvements.md @@ -1,86 +1,28 @@ --- description: >- This article describes the process for contributing quality improvements to the documentation. -ms.date: 03/30/2025 +ms.date: 02/12/2026 title: Contributing quality improvements --- # Contributing quality improvements -For [Hacktoberfest 2022][31], we [piloted a process][19] for contributing quality improvements to -the PowerShell content. This guide generalizes that process to define a low-friction way for -community members to improve to the quality of the documentation. +You don't have to be a subject matter expert or a documentation expert to contribute. If you see an +opportunity to improve the documentation, submit a pull request with your proposed improvement. This +guide outlines several simple ways that anyone can contribute quality improvements to the +documentation. We're focusing on these quality areas: - -- [Formatting code samples][05] -- [Formatting command syntax][06] -- [Link References][07] -- [Markdown linting][08] -- [Spelling][09] +- [Formatting code samples][03] +- [Formatting command syntax][04] +- [Link References][05] +- [Markdown linting][06] +- [Spelling][07] -## Project Tracking - -We're tracking contributions with the [PowerShell Docs Quality Contributions][23] GitHub Project. - -The project page has several views for the issues and PRs related to this effort: - - - -- The [Open issues][24] view shows all open issues. -- The [Completed][25] view shows merged PRs. -- The [PowerShell][26] view shows open issues for documentation in the [PowerShell-Docs][14], - [PowerShell-Docs-DSC][15], and [PowerShell-Docs-Modules][17] repositories. -- The [Windows PowerShell][27] view shows open issues for documentation in the - [windows-powershell-docs repository][21]. -- The [Azure PowerShell][28] view shows open issues for documentation in the - [azure-docs-powershell repository][12]. -- The [Open PRs][29] view shows all open PRs. - - - - ## Formatting code samples -All code samples should follow the [style guidelines][03] for PowerShell content. Those rules are +All code samples should follow the [style guidelines][02] for PowerShell content. Those rules are repeated in abbreviated form here for convenience: - All code blocks should be contained in a triple-backtick code fence (`` ``` ``). @@ -121,19 +63,19 @@ our conceptual documentation to use link references instead of inline links. For example, instead of: ```md -The [Packages tab][31] displays all available +The [Packages tab](https://www.powershellgallery.com/packages) displays all available packages in the PowerShell Gallery. ``` It should be: ```md -The [Packages tab][31] displays all available packages in the PowerShell Gallery. +The [Packages tab][01] displays all available packages in the PowerShell Gallery. ``` > [!NOTE] > When you replace an inline link, reflow the content to wrap at 100 characters. You can use the -> [reflow-markdown][30] VS Code extension to quickly reflow the paragraph. +> [reflow-markdown][09] VS Code extension to quickly reflow the paragraph. At the bottom of the file, add a markdown comment before the definition of the links. @@ -144,21 +86,22 @@ At the bottom of the file, add a markdown comment before the definition of the l Make sure that: -1. The links are defined in the order they appear in the document. 1. Every link points to the correct location. +1. Don't duplicate link reference definitions. If a link reference definition already exists for a + URL, reuse the existing reference instead of creating a new one. 1. The link reference definitions are at the bottom of the file after the markdown comment and are - in the correct order. + in the numeric order. ## Markdown linting For any article in one of the participating repositories, opening the article in VS Code displays linting warnings. Address any of these warnings you find, except: -- [MD022/blanks-around-headings/blanks-around-headers][11] for the `Synopsis` header in cmdlet +- [MD022/blanks-around-headings/blanks-around-headers][08] for the `Synopsis` header in cmdlet reference documents. For those items, the rule violation is intentional to ensure the documentation builds correctly with PlatyPS. -Make sure of the line lengths and use the [Reflow Markdown][30] extension to fix any long lines. +Make sure of the line lengths and use the [Reflow Markdown][09] extension to fix any long lines. ## Spelling @@ -166,71 +109,12 @@ Despite our best efforts, typos and misspellings get through and end up in the d mistakes make documentation harder to follow and localize. Fixing these mistakes makes the documentation more readable, especially for non-English speakers who rely on accurate translations. -## Process - -We encourage you to choose one or more of the quality areas and an article (or group of articles) -to improve. Use the following steps to guide your work: - - - -1. Check the [project][23] for issues filed for this effort to avoid duplicating efforts. -1. Open a new issue in the appropriate repository: - - Open an issue in [MicrosoftDocs/PowerShell-Docs][20] for PowerShell reference and conceptual - content. - - Open an issue in [MicrosoftDocs/PowerShell-Docs-Dsc][16] for DSC content - - Open an issue in [MicrosoftDocs/PowerShell-Docs-Modules][18] for Crescendo, PlatyPS, - PSScriptAnalyzer, SecretManagement, and SecretStore content. - - Open an issue in [MicrosoftDocs/azure-docs-powershell][13] for Azure PowerShell content. - - Open an issue in [MicrosoftDocs/windows-powershell-docs][22] for Windows PowerShell module - content. -1. Follow our [contributor's guide][01] to get setup for making your changes. -1. Submit your pull request. Ensure: - - 1. Your PR title has the `Quality:` prefix. - 1. Your PR body references the issue it resolves as an unordered list item and uses one of the - [linking keywords][10]. - - For example, if you're working on issue `123`, the body of your PR should include the - following Markdown: - - ```md - - resolves #123 - ``` - - After you submit the PR, the maintainers will review your work and work with you to get it - merged. - - - -[01]: /powershell/scripting/community/contributing/overview#prepare-to-make-a-contribution -[02]: /powershell/scripting/community/contributing/powershell-style-guide#formatting-command-syntax-elements -[03]: /powershell/scripting/community/contributing/powershell-style-guide#markdown-for-code-samples - -[05]: #formatting-code-samples -[06]: #formatting-command-syntax -[07]: #link-references -[08]: #markdown-linting -[09]: #spelling -[10]: https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword -[11]: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md022 -[12]: https://github.com/MicrosoftDocs/azure-docs-powershell -[13]: https://github.com/MicrosoftDocs/azure-docs-powershell/issues/new?template=02-quality.yml&title=Quality%3A+ -[14]: https://github.com/MicrosoftDocs/PowerShell-Docs -[15]: https://github.com/MicrosoftDocs/PowerShell-Docs-Dsc -[16]: https://github.com/MicrosoftDocs/PowerShell-Docs-Dsc/issues/new?template=02-quality.yml&title=Quality%3A+ -[17]: https://github.com/MicrosoftDocs/PowerShell-Docs-Modules -[18]: https://github.com/MicrosoftDocs/PowerShell-Docs-Modules/issues/new?template=02-quality.yml&title=Quality%3A+ -[19]: https://github.com/MicrosoftDocs/PowerShell-Docs/issues/9257 -[20]: https://github.com/MicrosoftDocs/PowerShell-Docs/issues/new?template=02-quality.yml&title=Quality%3A+ -[21]: https://github.com/MicrosoftDocs/windows-powershell-docs -[22]: https://github.com/MicrosoftDocs/windows-powershell-docs/issues/new?template=02-quality.yml&title=Quality%3A+ -[23]: https://github.com/orgs/MicrosoftDocs/projects/15 -[24]: https://github.com/orgs/MicrosoftDocs/projects/15/views/1 -[25]: https://github.com/orgs/MicrosoftDocs/projects/15/views/2 -[26]: https://github.com/orgs/MicrosoftDocs/projects/15/views/3 -[27]: https://github.com/orgs/MicrosoftDocs/projects/15/views/4 -[28]: https://github.com/orgs/MicrosoftDocs/projects/15/views/5 -[29]: https://github.com/orgs/MicrosoftDocs/projects/15/views/6 -[30]: https://marketplace.visualstudio.com/items?itemName=marvhen.reflow-markdown -[31]: https://www.powershellgallery.com/packages +[02]: powershell-style-guide.md#markdown-for-code-samples +[03]: #formatting-code-samples +[04]: #formatting-command-syntax +[05]: #link-references +[06]: #markdown-linting +[07]: #spelling +[08]: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md022 +[09]: https://marketplace.visualstudio.com/items?itemName=marvhen.reflow-markdown diff --git a/reference/docs-conceptual/learn/deep-dives/everything-about-exceptions.md b/reference/docs-conceptual/learn/deep-dives/everything-about-exceptions.md index 72103e2d13fa..17b065c9f7d1 100644 --- a/reference/docs-conceptual/learn/deep-dives/everything-about-exceptions.md +++ b/reference/docs-conceptual/learn/deep-dives/everything-about-exceptions.md @@ -599,7 +599,7 @@ terminating error by using `-ErrorAction Stop` or calling it from within a `try{ ### Public function templates -One last take a way I had with my conversation with Kirk Munro was that he places a +One last takeaway I had with my conversation with Kirk Munro was that he places a `try{...}catch{...}` around every `begin`, `process` and `end` block in all of his advanced functions. In those generic catch blocks, he has a single line using `$PSCmdlet.ThrowTerminatingError($PSItem)` to deal with all exceptions leaving his functions. diff --git a/reference/docs-conceptual/windows-powershell/update-notification-message.yml b/reference/docs-conceptual/windows-powershell/update-notification-message.yml index 60144608cfbc..3f55d3dfbba4 100644 --- a/reference/docs-conceptual/windows-powershell/update-notification-message.yml +++ b/reference/docs-conceptual/windows-powershell/update-notification-message.yml @@ -2,7 +2,7 @@ metadata: description: >- This article explains the intent of the update notification message in Windows PowerShell. - ms.date: 02/10/2026 + ms.date: 02/12/2026 ms.topic: faq title: Windows PowerShell update message FAQ @@ -34,8 +34,9 @@ sections: answer: | **You always get the message when you run Windows PowerShell 5.1.** - PowerShell 7 doesn't replace Windows PowerShell 5.1. PowerShell 7 installs side-by-side. - You can run either version. + PowerShell 7 and Windows PowerShell 5.1 are separate products. PowerShell 7 doesn't + replace Windows PowerShell 5.1. PowerShell 7 installs side-by-side. You can run either + version. - question: Can I disable the message? answer: No. There is no way to disable the message. @@ -43,9 +44,9 @@ sections: - question: How does Windows PowerShell 5.1 get updated? answer: | Windows PowerShell 5.1 is a built-in component of Windows. It's important to understand - that Windows PowerShell is no longer being developed. Microsoft only publishes security - updates for Windows PowerShell 5.1. All updates are managed through standard Windows - update channels. + that Windows PowerShell 5.1 is no longer being developed. Microsoft only publishes + security updates for Windows PowerShell 5.1. All updates are managed through standard + Windows update channels. - question: My install of Windows is up-to-date. Why am I still getting this message? answer: |