From e19ef48a6a75eb63a44872832a017120d2063709 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 19 Mar 2025 19:20:58 -0500 Subject: [PATCH 1/2] remove .vscode/styles from .gitignore --- .gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitignore b/.gitignore index 31efaeaa4333..4c24cd2eb25f 100644 --- a/.gitignore +++ b/.gitignore @@ -17,5 +17,4 @@ updatablehelp/ xhtml/ **/settings.json StaleContentReport.*.csv -.vscode/styles .vale/ From eeb1d03978cb8b7ea6eb40686b1246ff80f8cab3 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 26 Mar 2025 17:01:38 -0500 Subject: [PATCH 2/2] Update freshness of community content Full Acrolinx pass --- .../docs-conceptual/community/2020-updates.md | 2 +- .../docs-conceptual/community/2021-updates.md | 2 +- .../docs-conceptual/community/2022-updates.md | 2 +- .../docs-conceptual/community/2023-updates.md | 2 +- .../docs-conceptual/community/2024-updates.md | 2 +- .../community/community-support.md | 39 ++++++---- .../community/community-update.yml | 2 +- .../contributing/editorial-checklist.md | 45 +++++------ .../community/contributing/file-an-issue.md | 17 ++--- .../contributing/general-markdown.md | 75 ++++++++++--------- .../contributing/get-started-writing.md | 14 ++-- .../community/contributing/hackathons.md | 34 ++++----- .../contributing/labelling-in-github.md | 36 ++++----- .../community/contributing/managing-issues.md | 14 ++-- .../contributing/managing-pull-requests.md | 39 +++++----- .../community/contributing/overview.md | 9 +-- .../contributing/powershell-style-guide.md | 42 +++++------ .../contributing/product-terminology.md | 18 ++--- .../community/contributing/pull-requests.md | 49 ++++++------ .../contributing/quality-improvements.md | 34 ++++----- .../contributing/using-github-codespaces.md | 37 +++++---- .../docs-conceptual/community/digital-art.md | 2 +- 22 files changed, 261 insertions(+), 255 deletions(-) diff --git a/reference/docs-conceptual/community/2020-updates.md b/reference/docs-conceptual/community/2020-updates.md index 869d8a2a861f..31ac8e5daeef 100644 --- a/reference/docs-conceptual/community/2020-updates.md +++ b/reference/docs-conceptual/community/2020-updates.md @@ -1,6 +1,6 @@ --- description: List of changes to the PowerShell documentation for 2020 -ms.date: 02/02/2023 +ms.date: 03/30/2025 title: What's New in PowerShell Docs for 2020 --- diff --git a/reference/docs-conceptual/community/2021-updates.md b/reference/docs-conceptual/community/2021-updates.md index 10f23eef864e..de9ddbb51817 100644 --- a/reference/docs-conceptual/community/2021-updates.md +++ b/reference/docs-conceptual/community/2021-updates.md @@ -1,6 +1,6 @@ --- description: List of changes to the PowerShell documentation for 2021 -ms.date: 02/02/2023 +ms.date: 03/30/2025 title: What's New in PowerShell-Docs for 2021 --- # What's new in PowerShell Docs for 2021 diff --git a/reference/docs-conceptual/community/2022-updates.md b/reference/docs-conceptual/community/2022-updates.md index 41a8b1917334..d6bcb4b4feaa 100644 --- a/reference/docs-conceptual/community/2022-updates.md +++ b/reference/docs-conceptual/community/2022-updates.md @@ -1,6 +1,6 @@ --- description: List of changes to the PowerShell documentation for 2022 -ms.date: 06/28/2023 +ms.date: 03/30/2025 title: What's New in PowerShell-Docs for 2022 --- # What's new in PowerShell Docs for 2022 diff --git a/reference/docs-conceptual/community/2023-updates.md b/reference/docs-conceptual/community/2023-updates.md index e8ecfd4089b2..217cc2f7fc22 100644 --- a/reference/docs-conceptual/community/2023-updates.md +++ b/reference/docs-conceptual/community/2023-updates.md @@ -1,6 +1,6 @@ --- description: List of changes to the PowerShell documentation for 2023 -ms.date: 01/02/2024 +ms.date: 03/30/2025 title: What's New in PowerShell-Docs for 2023 --- # What's new in PowerShell Docs for 2023 diff --git a/reference/docs-conceptual/community/2024-updates.md b/reference/docs-conceptual/community/2024-updates.md index 945f8198c8db..9abfcdf08c98 100644 --- a/reference/docs-conceptual/community/2024-updates.md +++ b/reference/docs-conceptual/community/2024-updates.md @@ -1,6 +1,6 @@ --- description: List of changes to the PowerShell documentation for 2024 -ms.date: 01/02/2025 +ms.date: 03/30/2025 title: What's New in PowerShell-Docs for 2024 --- # What's new in PowerShell Docs for 2024 diff --git a/reference/docs-conceptual/community/community-support.md b/reference/docs-conceptual/community/community-support.md index df19b2ddb1ab..9324b3da32df 100644 --- a/reference/docs-conceptual/community/community-support.md +++ b/reference/docs-conceptual/community/community-support.md @@ -1,6 +1,6 @@ --- description: List of resources created for and by PowerShell users -ms.date: 11/16/2022 +ms.date: 03/30/2025 title: PowerShell community support resources --- # Getting support from the community @@ -8,19 +8,30 @@ title: PowerShell community support resources The PowerShell Community is a vibrant and active group of users. This article can help you get connected with other member of the community. -The PowerShell community can file issues, bugs, or feature requests in our -[GitHub](https://github.com/powershell/powershell/issues) repository. If you have questions, you may -find help from other members of the community in one of these public forums: +The PowerShell community can file issues, bugs, or feature requests in our [GitHub][07] repository. +If you have questions, you may find help from other members of the community in one of these public +forums: -- [User Groups](https://aka.ms/psusergroup) -- [PowerShell Tech Community](https://techcommunity.microsoft.com/t5/PowerShell/ct-p/WindowsPowerShell) -- [DSC Community](https://dsccommunity.org/) -- [PowerShell.org](https://forums.powershell.org/) -- [Stack Overflow](https://stackoverflow.com/questions/tagged/powershell) -- [r/PowerShell subreddit](https://www.reddit.com/r/PowerShell/) +- [User Groups][04] +- [PowerShell Tech Community][09] +- [DSC Community][05] +- [PowerShell.org][06] +- [Stack Overflow][08] +- [r/PowerShell subreddit][10] - PowerShell Virtual User Group - join via: - - [Slack](https://aka.ms/psslack) - - [Discord](https://aka.ms/psdiscord) + - [Slack][03] + - [Discord][02] -For information about our support policy, see the -[PowerShell Support Lifecycle](/powershell/scripting/powershell-support-lifecycle). +For information about our support policy, see the [PowerShell Support Lifecycle][01]. + + +[01]: /powershell/scripting/powershell-support-lifecycle +[02]: https://aka.ms/psdiscord +[03]: https://aka.ms/psslack +[04]: https://aka.ms/psusergroup +[05]: https://dsccommunity.org/ +[06]: https://forums.powershell.org/ +[07]: https://github.com/powershell/powershell/issues +[08]: https://stackoverflow.com/questions/tagged/powershell +[09]: https://techcommunity.microsoft.com/t5/PowerShell/ct-p/WindowsPowerShell +[10]: https://www.reddit.com/r/PowerShell/ diff --git a/reference/docs-conceptual/community/community-update.yml b/reference/docs-conceptual/community/community-update.yml index b5573b7eb234..40a4f0ebbca8 100644 --- a/reference/docs-conceptual/community/community-update.yml +++ b/reference/docs-conceptual/community/community-update.yml @@ -9,7 +9,7 @@ metadata: ms.topic: landing-page # Required author: sdwheeler #Required; your GitHub user alias, with correct capitalization. ms.author: sewhee #Required; Microsoft alias of author; optional team alias. - ms.date: 02/03/2025 + ms.date: 03/30/2025 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | # overview | quickstart | reference | tutorial | video | whats-new diff --git a/reference/docs-conceptual/community/contributing/editorial-checklist.md b/reference/docs-conceptual/community/contributing/editorial-checklist.md index acbc011cd460..3ecc02636d14 100644 --- a/reference/docs-conceptual/community/contributing/editorial-checklist.md +++ b/reference/docs-conceptual/community/contributing/editorial-checklist.md @@ -1,17 +1,17 @@ --- -description: This is a summarized list of rules for editing PowerShell documentation. -ms.date: 11/16/2022 +description: This article contains a summarized list of rules for editing PowerShell documentation. +ms.date: 03/30/2025 title: Editorial checklist --- # Editor's checklist -This is a summary of rules to apply when writing new or updating existing articles. See other -articles in the Contributor's Guide for detailed explanations and examples of these rules. +This article contains a summarized list of rules for writing or editing PowerShell documentation. +See other articles in the Contributor's Guide for detailed explanations and examples of these rules. ## Metadata - `ms.date`: must be in the format **MM/DD/YYYY** - - Change the date when there is a significant or factual update + - Change the date when there's a significant or factual update - Reorganizing the article - Fixing factual errors - Adding new information @@ -31,7 +31,7 @@ articles in the Contributor's Guide for detailed explanations and examples of th - File paths `C:\Program Files\PowerShell`, `/usr/bin/pwsh` - URLs that aren't meant to be clickable in the document - Property or parameter values -- Use bold for property names, parameter names, class names, module names, entity names, object or +- Use bold for property names, parameter names, class names, module names, entity names, object, or type names - Bold is used for semantic markup, not emphasis - Bold - use asterisks `**` @@ -45,39 +45,39 @@ articles in the Contributor's Guide for detailed explanations and examples of th ### Headers -- H1 is first - only one H1 per article +- Start with H1 first - only one H1 per article - Use [ATX Headers][1] only - Use sentence case for all headers - Don't skip levels - no H3 without an H2 -- Max depth of H3 or H4 -- Blank line before and after -- PlatyPS enforces specific headers in its schema - don't add or remove headers +- Limit header depth to H3 or H4 +- Add blank lines before and after +- Don't add or remove headers - PlatyPS enforces specific headers in its schema ### Code blocks -- Blank line before and after +- Add blank lines before and after - Use tagged code fences - **powershell**, **Output**, or other appropriate language ID -- Untagged fence - syntax blocks or other shells -- Put output in separate code block except for basic examples where you don't intend the for the +- Use untagged code fence for syntax blocks +- Put output in separate code block except for basic examples where you don't intend for the reader to use the **Copy** button - See list of [supported languages][2] ### Lists -- Indented properly -- Blank line before first item and after last item -- Bullet - use hyphen (`-`) not asterisk (`*`) to reduce confusion with emphasis -- For numbered lists, all numbers are "1." +- Indent properly +- Add blank lines before first item and after last item +- Use hyphen (`-`) for bullets not asterisk (`*`) to reduce confusion with emphasis +- Use `1.` for all items in a numbered list ## Terminology -- PowerShell vs. Windows PowerShell +- Use _PowerShell_ vs. _Windows PowerShell_ - See [Product Terminology][3] ## Cmdlet reference examples - Must have at least one example in cmdlet reference -- Examples should be just enough code to demonstrate the usage +- Examples should be only enough code to demonstrate the usage - PowerShell syntax - Use full names of cmdlets and parameters - no aliases - Use splatting for parameters when the command line gets too long @@ -108,11 +108,12 @@ articles in the Contributor's Guide for detailed explanations and examples of th ## Linking to other documents - When linking outside the docset or between cmdlet reference and conceptual - - Use site-relative URLs when linking to Microsoft Learn (remove `https://learn.microsoft.com/en-us`) - - don't include locales in URLs on Microsoft properties (eg. remove `/en-us` from URL) + - Use site-relative URLs when linking to Microsoft Learn (remove + `https://learn.microsoft.com/en-us`) + - don't include locales in URLs on Microsoft properties (remove `/en-us` from URL) - All URLs to external websites should use HTTPS unless that's not valid for the target site - When linking within the docset - - Use the relative filepath (e.g. `../folder/file.md`) + - Use the relative filepath (`../folder/file.md`) - All paths use forward-slash (`/`) characters - Image links should have unique alt text diff --git a/reference/docs-conceptual/community/contributing/file-an-issue.md b/reference/docs-conceptual/community/contributing/file-an-issue.md index d54d2c8ed4a7..2c0570531848 100644 --- a/reference/docs-conceptual/community/contributing/file-an-issue.md +++ b/reference/docs-conceptual/community/contributing/file-an-issue.md @@ -1,6 +1,6 @@ --- description: This article explains how to give feedback about the PowerShell documentation. -ms.date: 07/26/2022 +ms.date: 03/30/2025 title: How to file a PowerShell-Docs issue --- # How to file a PowerShell-Docs issue @@ -15,24 +15,23 @@ There are two ways to create an issue: For a full description of the feedback controls, see the Docs Team blog announcing this [feature][1]. -At the bottom of most pages on `learn.microsoft.com`, you'll see two feedback buttons. One is a link +At the bottom of most pages on `learn.microsoft.com`, there are two feedback buttons. One is a link for product feedback and one is for documentation feedback. The documentation feedback requires a GitHub account. Clicking the button takes you in GitHub and presents an issue template. Enter your feedback and submit the form. > [!NOTE] -> The feedback tool not a support channel. This is a way to ask questions to clarify documentation -> or to report errors and omissions. If you need technical support, see [Community resources][2]. +> The feedback tool not a support channel. It's a way to ask questions to clarify documentation or +> to report errors and omissions. If you need technical support, see [Community resources][2]. ## Filing issues on GitHub -To file a GitHub issue directly, you can click the [New issue][3] button in the PowerShell-Docs -repository. Click the **Get started** button for the issue you want to create. The GitHub issue +To file a GitHub issue directly, you can select the [New issue][3] button in the PowerShell-Docs +repository. Select the **Get started** button for the issue you want to create. The GitHub issue template helps you provide the information needed to address the problem you're reporting. -Before you file a new issue, read through existing issues to see if your problem has already been -reported. This helps avoid duplication and your issue may have been answered already. If you find an -existing issue, you can add your comments, related questions, or answers. +To avoid duplication, search the existing issues to see if someone else has already reported it. If +you find an existing issue, you can add your comments, related questions, or answers. ## Next steps diff --git a/reference/docs-conceptual/community/contributing/general-markdown.md b/reference/docs-conceptual/community/contributing/general-markdown.md index 3b67603caa65..e0785cace3e1 100644 --- a/reference/docs-conceptual/community/contributing/general-markdown.md +++ b/reference/docs-conceptual/community/contributing/general-markdown.md @@ -1,21 +1,20 @@ --- description: This article provides specific guidance for using Markdown in our documentation. -ms.date: 08/01/2024 +ms.date: 03/30/2025 title: Markdown best practices --- # Markdown best practices -This article provides specific guidance for using Markdown in our documentation. This is not a -tutorial for Markdown, but lists specific rules and best practices for Markdown in the PowerShell -docs. If you need a tutorial for Markdown, see this [Markdown cheatsheet][12]. +This article provides specific guidance for using Markdown in our documentation. It isn't a tutorial +for Markdown. If you need a tutorial for Markdown, see this [Markdown cheatsheet][12]. The Microsoft Open Publishing System (OPS) that builds our documentation uses [markdig][06] to process the Markdown documents. Markdig parses the documents based on the rules of the latest [CommonMark][10] specification. OPS follows the CommonMark specification and adds some extensions for platform-specific features, such as tables and alerts. -The CommonMark specification is much stricter about the construction of some Markdown elements. Pay -close attention to the details provided in this document. +The CommonMark specification is stricter about the construction of some Markdown elements. Pay close +attention to the details provided in this document. We use the [markdownlint][08] extension in VS Code to enforce our style and formatting rules. This extension is installed as part of the **Learn Authoring Pack**. @@ -24,11 +23,12 @@ extension is installed as part of the **Learn Authoring Pack**. Blank lines also signal the end of a block in Markdown. -- There should be a single blank between Markdown blocks of different types -- for example, between +- Put a single blank between Markdown blocks of different types; for example, between a paragraph and a list or header. - Don't use more than one blank line. Multiple blank lines render as a single blank line in HTML, therefore the extra blank lines are unnecessary. -- Within a code block, consecutive blank lines break the code block. +- Don't use put multiple consecutive blank lines in a code block, consecutive blank lines break the + code block. Spacing is significant in Markdown. @@ -37,29 +37,31 @@ Spacing is significant in Markdown. ## Titles and headings -Only use [ATX headings][07] (`#` style, as opposed to `=` or `-` style headers). +Use [ATX headings][07] only (`#` style, as opposed to `=` or `-` style headers). - Use sentence case - only proper nouns and the first letter of a title or header should be capitalized -- There must be a single space between the `#` and the first letter of the heading -- Headings should be surrounded by a single blank line -- Only one H1 per document -- Header levels should increment by one -- don't skip levels +- Include a single space between the `#` and the first letter of the heading +- Surround headings with single blank line +- Don't use more than one H1 per document + - It should be the first header + - It should match the title of the article +- Increment header levels by one - don't skip levels - Limit depth to H3 or H4 - Avoid using bold or other markup in headers ## Limit line length to 100 characters -This applies to conceptual articles and cmdlet reference. For `about_` topics, limit the line -length to 79 characters. Limiting the line length improves the readability of `git` diffs and -history. It also makes it easier for other writers to make contributions. +For conceptual articles and cmdlet reference, limit lines to 100 characters. For `about_` articles, +limit the line length to 79 characters. Limiting the line length improves the readability of `git` +diffs and history. It also makes it easier for other writers to make contributions. Use the [Reflow Markdown][09] extension in VS Code to reflow paragraphs to fit the prescribed line length. -Some content types can't be easily reflowed. For example, the code inside of code blocks may also be -difficult to reflow, depending on the content and the code language. And you can't reflow a table. -In these cases, use your best judgment to keep the content as close to the 100-character limit as +Some content types can't be easily reflowed. For example, the code inside of code blocks can also be +difficult to reflow, depending on the content and the code language. You can't reflow a table. In +these cases, use your best judgment to keep the content as close to the 100-character limit as possible. ## Emphasis @@ -70,21 +72,21 @@ mark the emphasis. However, to be consistent and show intent: - Use `**` for bold - Use `_` for italics -Following this pattern makes it easier for others to understand the intent of the markup when there -is a mix of bold and italics in a document. +Following this pattern makes it easier for others to understand the intent of the markup when +there's a mix of bold and italics in a document. ## Lists If your list has multiple sentences or paragraphs, consider using a sublevel header rather than a list. -List should be surrounded by a single blank line. +Surround lists with a single blank line. ### Unordered lists - Don't end list items with a period unless they contain multiple sentences. -- Use the hyphen character (`-`) for list item bullets. This avoids confusion with emphasis markup - that uses the asterisk (`*`). +- Use the hyphen character (`-`) for list item bullets to avoid confusion with emphasis markup that + uses the asterisk (`*`). - To include a paragraph or other elements under a bullet item, insert a line break and align indentation with the first character after the bullet. @@ -129,8 +131,8 @@ This is a list that contains child elements under a bullet item. For example: ```Markdown -1. For the first element, insert a single space after the 1. Long sentences should be wrapped to the - next line and must line up with the first character after the numbered list marker. +1. For the first element, insert a single space after the `1`. Long sentences should be wrapped to + the next line and must line up with the first character after the numbered list marker. To include a second element, insert a line break after the first and align indentations. The indentation of the second element must line up with the first character after the numbered list @@ -141,8 +143,8 @@ For example: The resulting Markdown is rendered as follows: -1. For the first element, insert a single space after the 1. Long sentences should be wrapped to the - next line and must line up with the first character after the numbered list marker. +1. For the first element, insert a single space after the `1`. Long sentences should be wrapped to + the next line and must line up with the first character after the numbered list marker. To include a second element, insert a line break after the first and align indentations. The indentation of the second element must line up with the first character after the numbered list @@ -227,8 +229,11 @@ Warning block ## Markdown extension - Tables -A table is an arrangement of data with rows and columns, consisting of a single header row, a -delimiter row separating the header from the data, and zero or more data rows. +A table is an arrangement of data with rows and columns consisting of: + +- A single header row +- A delimiter row separating the header from the data +- Zero or more data rows Each row consists of cells containing arbitrary text separated by pipes (`|`). A leading and trailing pipe is also recommended for clarity. Spaces between pipes and cell content are trimmed. @@ -237,9 +242,11 @@ Block-level elements can't be inserted in a table. All content of a row must be The delimiter row consists of cells whose only content are hyphens (`-`), and optionally, a leading or trailing colon (`:`), or both, to indicate left, right, or center alignment respectively. -For small tables, consider using a list instead. Lists are easier to maintain and read, can be -reflowed to fit within the 100-character line limit, and are more accessible for users that use -screen readers for visual assistance. +For small tables, consider using a list instead. Lists are: + +- Easier to maintain and read +- Can be reflowed to fit within the 100-character line limit +- More accessible for users that use screen readers for visual assistance For more information, see _Tables_ section of [Markdown reference for Microsoft Learn][05]. @@ -253,7 +260,7 @@ For more information, see _Tables_ section of [Markdown reference for Microsoft - All URLs to external websites should use HTTPS unless that isn't valid for the target site. - Links must have a friendly name, usually the title of the linked article - Avoid using backticks, bold, or other markup inside the brackets of a hyperlink. -- Bare URLs may be used when you're documenting a specific URI but must be enclosed in backticks. +- Bare URLs can be used when you're documenting a specific URI but must be enclosed in backticks. For example: ```Markdown diff --git a/reference/docs-conceptual/community/contributing/get-started-writing.md b/reference/docs-conceptual/community/contributing/get-started-writing.md index 57076a72ead1..18c12effb105 100644 --- a/reference/docs-conceptual/community/contributing/get-started-writing.md +++ b/reference/docs-conceptual/community/contributing/get-started-writing.md @@ -1,6 +1,6 @@ --- description: This article is an overview of how to get started as a contributor to the PowerShell documentation. -ms.date: 01/17/2025 +ms.date: 03/30/2025 title: Get started contributing to PowerShell documentation --- # Get started contributing to PowerShell documentation @@ -74,7 +74,7 @@ documentation. All articles must be included in the Table of Contents (TOC). The location should be included in the issue discussion. > [!NOTE] -> The TOC for reference content is autogenerated by the publishing system. You don't have to update +> The publishing system autogenerates the TOC for reference content. You don't have to update > the TOC. ## Updating existing articles @@ -89,7 +89,7 @@ Apply the appropriate change to each version of the file. The PowerShell documentation is written in English and translated into 17 other languages. The English content is stored in the GitHub repository named `MicrosoftDocs/PowerShell-Docs`. Issues -found in the translated content should be submitted to the English repository. +found in the translated content should be submitted to this repository. All translations start from the English content first. We use both human and machine translation. @@ -98,11 +98,11 @@ All translations start from the English content first. We use both human and mac | Human translation | de-DE, es-ES, fr-FR, it-IT, ja-JP, ko-KR, pt-BR, ru-RU, zh-CN, zh-TW | | Machine translation | cs-CZ, hu-HU, nl-NL, pl-PL, pt-PT, sv-SE, tr-TR | -The content translated by machine translation may not always result in correct word choices and +The content translated by machine translation might not always result in correct word choices and grammar. If you find an error in translation for any language, rather than in the technical details of the article, open an issue explaining why you think the translation is wrong. -Some translation issues can be fixed by changing the English source files. However, some issues may +Some translation issues can be fixed by changing the English source files. However, some issues can require updates to our internal translation system. For those cases, we must submit the issue to our internal localization team for review and response. @@ -120,8 +120,8 @@ should be made in a working branch in you copy of the PowerShell-Docs. If you're edit** method in GitHub, these steps are handled for you. If you're using the **full GitHub workflow**, you must be set up to [work locally][7]. -Both methods end with the creation of a Pull Request (PR). See [Submitting a pull request][8] for -more information and best practices. +Both methods end with the creation of a Pull Request (PR). For more information and best practices, +see [Submitting a pull request][8]. [1]: https://github.com/MicrosoftDocs/PowerShell-Docs diff --git a/reference/docs-conceptual/community/contributing/hackathons.md b/reference/docs-conceptual/community/contributing/hackathons.md index f099eafbb4c8..89007d6bfb3d 100644 --- a/reference/docs-conceptual/community/contributing/hackathons.md +++ b/reference/docs-conceptual/community/contributing/hackathons.md @@ -1,6 +1,6 @@ --- description: This article describes how we manage and support hack-a-thon events like Hacktoberfest. -ms.date: 10/04/2022 +ms.date: 03/30/2025 title: Hacktoberfest and other hack-a-thon events --- # Hacktoberfest and other hack-a-thon events @@ -13,8 +13,8 @@ in Hacktoberfest. ## How to contribute Before you can contribute to an open source repo, you must first configure your account to -contribute to Microsoft Learn. If you have never completed this process, start by -[signing up for a GitHub account][01]. Be sure to [install Git and the Markdown tools][02]. +contribute to Microsoft Learn. If you're new to this process, start by signing up for a +[GitHub account][01]. Be sure to [install Git and the Markdown tools][02]. To get credit for participation, [register with Hacktoberfest][03] and read their [participation guide][04]. @@ -22,18 +22,18 @@ To get credit for participation, [register with Hacktoberfest][03] and read thei ## Find a repo that needs your help The PowerShell-Docs team is supporting Hacktoberfest contributions for several PowerShell -documentation repositories. We have defined a set of cleanup tasks designed to be simple for first -time contributors. Full information can be found in the [Hacktoberfest meta-issue][05]. +documentation repositories. We defined a set of cleanup tasks designed to be simple for first time +contributors. Full information can be found in the [Hacktoberfest meta-issue][05]. To be successful with these tasks, you should: - Have a general understanding of PowerShell syntax - Have an understanding of [splatting][06] - Be able to read and follow the [PowerShell-Docs style guide][07] and [Editorial checklist][08] -- Basic familiarity with Markdown +- Have basic familiarity with Markdown -Before contributing should read the meta-issue. When you are ready to start, open a new issue using -the Hacktoberfest issue template (linked below): +Before contributing should read the meta-issue. When you're ready to start, open a new issue using +the Hacktoberfest issue template by using one of the following links: - [MicrosoftDocs/PowerShell-Docs][09] - [MicrosoftDocs/PowerShell-Docs-DSC][10] @@ -47,21 +47,19 @@ To have a successful contribution to an open source Microsoft Learn repository, and impactful PR. The following examples from the official Hacktoberfest site are considered **_low-quality contributions_**: -- PRs that are automated (for example, scripted opening PRs to remove whitespace, fix typos, or - optimize images) -- PRs that are disruptive (for example, taking someone else's branch or commits and making a PR) -- PRs that are regarded by a project maintainer as a hindrance vs. helping -- A submission that's clearly an attempt to simply +1 your PR count for October - -Finally, one PR to fix a typo is fine, but five PRs to remove a stray whitespace are not. +- PRs containing bulk automated changes + - Example: scripted PRs to remove whitespace, fix common spelling, or optimize images + - Submit an issue first describing the automated changes you want to make +- PRs deemed disruptive (for example, taking someone else's branch or commits and making a PR) +- PRs deemed a hindrance vs. helping +- PRs that are clearly an attempt to increment your PR count for October For more information, see [Hacktoberfest: Values][14]. ### Open a PR -A _PR_ provides a convenient way for a contributor to propose a set of changes. When opening a PR, -specify in the original comment that it's intended to contribute to _hacktoberfest_. Successful PRs -have these common characteristics: +A _PR_ provides a convenient way for a contributor to propose a set of changes. Successful PRs have +these common characteristics: - The PR adds value. - The contributor is receptive to feedback. diff --git a/reference/docs-conceptual/community/contributing/labelling-in-github.md b/reference/docs-conceptual/community/contributing/labelling-in-github.md index 8492269e0cf8..266783e28d64 100644 --- a/reference/docs-conceptual/community/contributing/labelling-in-github.md +++ b/reference/docs-conceptual/community/contributing/labelling-in-github.md @@ -1,14 +1,14 @@ --- description: This article explains how the PowerShell-Docs team uses labels in GitHub. -ms.date: 12/16/2022 -title: Labelling in GitHub +ms.date: 03/30/2025 +title: Labeling in GitHub --- -# Labelling in GitHub +# Labeling in GitHub This article documents how we label issues and pull requests in the PowerShell-Docs repository. -This article is designed to be a job aid for members of the PowerShell-Docs team. It's published -here to provide process transparency for our public contributors. +This article is designed to be a job aid for members of the PowerShell-Docs team. We publish this +information here to provide process transparency for our public contributors. Labels always have a name and a description that is prefixed with their type. @@ -18,11 +18,11 @@ Area labels identify the parts of PowerShell or the documentation that the issue | Label | Related Content | | :----------------------- | :--------------------------------------------------------------------------------------- | -| `area-about` | The `about_*` topic articles. | +| `area-about` | The `about_*` articles. | | `area-archive` | The [Microsoft.PowerShell.Archive][03] module. | | `area-cim` | The [CimCmdlets][01] module. | | `area-community` | Community-facing projects, including the contributor's guide and monthly updates. | -| `area-conceptual` | Conceptual (non-reference) articles. | +| `area-conceptual` | Conceptual articles (not cmdlet reference). | | `area-console` | The console host | | `area-core` | The [Microsoft.PowerShell.Core][04] module. | | `area-crescendo` | The [Crescendo][02] module. | @@ -134,17 +134,17 @@ status labels when they're closed without a related PR. Tag labels add independent context for work items. -| Label | Purpose | -| :------------------------ | :------------------------------------------------------------------------ | -| `in-progress` | Someone is actively working on the item | -| `go-live` | The work item is related to a specific release | -| `doc-a-thon` | The work item is related to a doc-a-thon | -| `up-for-grabs` | Any contributor may volunteer to resolve the work item | -| `hacktoberfest-accepted` | The PR is accepted for inclusion in [#hacktoberfest][17] | -| `hacktoberfest-candidate` | The PR is a candidate for inclusion in [#hacktoberfest][17] | -| `needs-triage` | The issue needs to be triaged by the team before it is ready to be worked | -| `code-of-conduct` | Closed for spam, trolling, or code of conduct violations | -| `do-not-merge` | The PR isn't meant to be merged | +| Label | Purpose | +| :------------------------ | :------------------------------------------------------------------- | +| `in-progress` | Someone is actively working on the item | +| `go-live` | The work item is related to a specific release | +| `doc-a-thon` | The work item is related to a doc-a-thon | +| `up-for-grabs` | Any contributor can volunteer to resolve the work item | +| `hacktoberfest-accepted` | The PR is accepted for inclusion in [#hacktoberfest][17] | +| `hacktoberfest-candidate` | The PR is a candidate for inclusion in [#hacktoberfest][17] | +| `needs-triage` | The issue must be triaged by the team before it's ready to be worked | +| `code-of-conduct` | Closed for spam, trolling, or code of conduct violations | +| `do-not-merge` | The PR isn't meant to be merged | ## Waiting labels diff --git a/reference/docs-conceptual/community/contributing/managing-issues.md b/reference/docs-conceptual/community/contributing/managing-issues.md index 9f494199dcb5..da8c8813866c 100644 --- a/reference/docs-conceptual/community/contributing/managing-issues.md +++ b/reference/docs-conceptual/community/contributing/managing-issues.md @@ -1,13 +1,13 @@ --- description: This article explains how the PowerShell-Docs team manages issues. -ms.date: 11/09/2022 +ms.date: 03/30/2025 title: How we manage issues --- # How we manage issues This article documents how we manage issues in the PowerShell-Docs repository. This article is -designed to be a job aid for members of the PowerShell-Docs team. It's published here to provide -process transparency for our public contributors. +designed to be a job aid for members of the PowerShell-Docs team. We publish this information here +to provide process transparency for our public contributors. ## Sources of issues @@ -20,7 +20,7 @@ process transparency for our public contributors. 80% of new issues are closed within 3 business days. -- Triaged - 1 business days +- Triaged - 1 business day - Fix or change - 10 business days ### Labeling & Milestones @@ -41,8 +41,8 @@ For more information on specific labels, see [Labeling][02]. Issues and PRs should be tagged with the appropriate milestone. If the issue doesn't apply to a specific version, then no milestone is used. PRs and related issues for changes that have yet to be -merged into the PowerShell code base should be assigned to the **Future** milestone. After the code -change has been merged, change the milestone to the appropriate version. +merged into the PowerShell code base should be assigned to the **Future** milestone. After you merge +the change, update the milestone to the appropriate version. | Milestone | Description | | --------- | ----------------------------------------- | @@ -82,7 +82,7 @@ meets weekly to discuss difficult issues need triage and prioritize the work. - Edit the issue to remove any offensive content, if necessary - Enter a comment indicating the issue is spam, close the issue, and then lock it to prevent further comments -- Each violation should be discussed in the weekly triage to determine the need for further action +- Discuss each violation in the regular triage meeting to determine the need for further action [01]: https://github.com/PowerShell/PowerShell/issues/new/choose diff --git a/reference/docs-conceptual/community/contributing/managing-pull-requests.md b/reference/docs-conceptual/community/contributing/managing-pull-requests.md index 27838619d13d..22590fb8bcc2 100644 --- a/reference/docs-conceptual/community/contributing/managing-pull-requests.md +++ b/reference/docs-conceptual/community/contributing/managing-pull-requests.md @@ -1,25 +1,24 @@ --- description: This article explains how the PowerShell-Docs team manages pull requests. -ms.date: 07/25/2022 +ms.date: 03/30/2025 title: How we manage pull requests --- # Managing pull requests This article documents how we manage pull requests in the PowerShell-Docs repository. This article -is designed to be a job aid for members of the PowerShell-Docs team. It's published here to provide -process transparency for our public contributors. +is designed to be a job aid for members of the PowerShell-Docs team. We publish this information +here to provide process transparency for our public contributors. ## Best practices -- The person submitting the PR shouldn't merge the PR without a peer review. +- Request a review. The person submitting the PR shouldn't merge the PR without a peer review. - Assign the peer reviewer when the PR is submitted. Early assignment allows the reviewer to respond sooner with editorial remarks. -- Use comments to describe the nature of the change being submitted. Be sure to @mention the - reviewer. For example, if the change is minor and you don't need a full technical review, explain - this in a comment. -- Reviewers should use the comment suggestion feature, when appropriate, to make it easier for the - author to accept the suggested change. For more information, see - [Reviewing proposed changes in a pull request][1]. +- Use comments to describe the nature of the change being submitted. For example, if the change is + minor, explain the change and that you don't need a full technical review. Be sure to @mention the + reviewer. +- Use the comment suggestion feature to make it easier for the author to accept the suggested + change. For more information, see [Reviewing proposed changes in a pull request][1]. ## PR Process steps @@ -34,7 +33,7 @@ process transparency for our public contributors. 1. Both: Review preview rendering 1. Both: Review validation report - fix warnings and errors 1. Reviewer: Mark review "Approved" -1. Repo Admin: Merge PR (see below for criteria) +1. Repo Maintainer: Merge PR ## Content Reviewer Checklist @@ -47,7 +46,7 @@ See the [editorial checklist][4] for a more comprehensive list. - Validate markdown correctness - See style guide for content-specific formatting rules - Reorganize examples as follows: - - Intro sentence(s) + - Intro paragraph - Code and output - Detailed explanation of code (as necessary) - Check hyperlinks for accuracy @@ -60,12 +59,12 @@ See the [editorial checklist][4] for a more comprehensive list. - Remove locales from URLs - Simplify URLs pointing to `learn.microsoft.com` - Verify versioned content is correct across all versions - - Review the [versioned content change report][5] to see summarized changes + - Review the [versioned content change report][5] ## Branch Merge Process -The `main` branch is the only branch that's merged into `live`. Merges from short-lived (working) -branches should be squashed. +The `main` branch is the only branch that should be merged into `live`. Merges from short-lived +(working) branches should be squashed before merging into `main`. | _Merge from/to_ | _release-branch_ | _main_ | _live_ | | ---------------- | :--------------: | :--------------: | :---------: | @@ -101,10 +100,12 @@ Docs platform, so the values set in these 3 places will be ignored. Please remov ``` When a PR is merged, the HEAD of the target branch is changed. Any open PRs that were based on the -previous HEAD are now outdated. The outdated PR can be merged using Admin rights to override the -merge warnings in GitHub. This is safe to do if the previously merged PRs haven't touched the same -files. Clicking the **Update Branch** button is the safest option. Choose **Update with rebase** -option. For more information see [Updating your pull request branch][9]. +previous HEAD are now outdated. A Maintainer has the right required to override the merge warnings +and merge the outdated PR in GitHub. Merging an outdated PR is safe if the previously merged PRs +didn't touch the same files. + +To update the PR, select the **Update Branch** button. Choose **Update with rebase** option. For +more information, see [Updating your pull request branch][9]. ## Publishing to Live diff --git a/reference/docs-conceptual/community/contributing/overview.md b/reference/docs-conceptual/community/contributing/overview.md index 2eddda33938d..a8378676680c 100644 --- a/reference/docs-conceptual/community/contributing/overview.md +++ b/reference/docs-conceptual/community/contributing/overview.md @@ -1,6 +1,6 @@ --- description: This article outlines the steps required to contribute to the PowerShell documentation. -ms.date: 07/25/2022 +ms.date: 03/30/2025 title: Contributing to PowerShell documentation --- # Contributing to PowerShell documentation @@ -57,13 +57,12 @@ Use the full GitHub workflow when you're making significant changes. If you're n Microsoft, our PR validation system adds a comment to the pull request asking you to sign the online [Contribution Licensing Agreement (CLA)][15]. You must complete this step before we can review or accept your pull request. Signing the CLA is only required the first time you submit a PR in the -repository. You will be asked to sign the CLA for each time you contribute to a new repository. +repository. You might be asked to sign the CLA for each time you contribute to a new repository. ## Code of conduct -All repositories that publish to Microsoft Learn have adopted the -[Microsoft Open Source Code of Conduct][16] or the -[.NET Foundation Code of Conduct][17]. For more +All repositories that publish to Microsoft Learn adhere to the +[Microsoft Open Source Code of Conduct][16] or the [.NET Foundation Code of Conduct][17]. For more information, see the [Code of Conduct FAQ][18]. ## Next steps diff --git a/reference/docs-conceptual/community/contributing/powershell-style-guide.md b/reference/docs-conceptual/community/contributing/powershell-style-guide.md index 7e3f68195cae..f22bf0fcf838 100644 --- a/reference/docs-conceptual/community/contributing/powershell-style-guide.md +++ b/reference/docs-conceptual/community/contributing/powershell-style-guide.md @@ -1,6 +1,6 @@ --- description: This article provides the rules of style for writing PowerShell documentation. -ms.date: 05/09/2024 +ms.date: 03/30/2025 title: PowerShell-Docs style guide --- # PowerShell-Docs style guide @@ -10,8 +10,8 @@ information outlined in the [Overview][10]. ## Formatting command syntax elements -Use the following rules to format elements of the PowerShell language when they are used in a -sentence. +Use the following rules to format elements of the PowerShell language when the elements are used in +a sentence. - Always use the full name for cmdlets and parameters in the proper Pascal case - Only use an alias when you're specifically demonstrating the alias @@ -23,8 +23,8 @@ sentence. - Property names - Parameter names - By default, use the parameter without the hyphen prefix. - - When illustrating the use of a parameter with the hyphen prefix, the parameter should be - wrapped in backticks. + - Use parameter name with the hyphen if you're illustrating syntax. Wrap the parameter in + backticks. For example: @@ -47,7 +47,7 @@ sentence. - File and directory paths - Inline command syntax examples - See [Markdown for code samples][04] - This example show some backtick examples: + This example shows some backtick examples: ~~~markdown The following code uses `Get-ChildItem` to list the contents of `C:\Windows` and assigns @@ -58,7 +58,7 @@ sentence. ``` ~~~ - This examples shows command syntax inline: + This example shows command syntax inline: ```markdown To start the spooler service on a remote computer named DC01, you type: @@ -75,7 +75,7 @@ Markdown supports two different code styles: - **Code spans (inline)** - marked by a single backtick (`` ` ``) character. Used within a paragraph rather than as a standalone block. - **Code blocks** - a multi-line block surrounded by triple-backtick (`` ``` ``) strings. Code - blocks may also have a language label following the backticks. The language label enables syntax + blocks can also have a language label following the backticks. The language label enables syntax highlighting for the contents of the code block. All code blocks should be contained in a code fence. Never use indentation for code blocks. Markdown @@ -83,7 +83,7 @@ allows this pattern but it can be problematic and should be avoided. A code block is one or more lines of code surrounded by a triple-backtick (`` ``` ``) code fence. The code fence markers must be on their own line before and after the code sample. The opening -marker may have an optional language label. The language label enables syntax highlighting on the +marker can have an optional language label. The language label enables syntax highlighting on the rendered webpage. For a full list of supported language tags, see [Fenced code blocks][01] in the centralized @@ -126,10 +126,10 @@ for (; ; ) ### Illustrative examples -Illustrative examples are used to explain a PowerShell concept. In general you should -[Avoid using PowerShell prompts in examples][03]. However, illustrative examples aren't meant to be -copied and pasted for execution. These are most commonly used for simple examples that are easy to -understand. The code block can include the PowerShell prompt and example output. +Illustrative examples are used to explain a PowerShell concept. Yo`u should +[Avoid using PowerShell prompts in examples][03] whenever possible. However, illustrative examples +aren't meant to be copied and pasted for execution. They're most commonly used for simple examples +that are easy to understand. You may include the PowerShell prompt and example output. Here's a simple example illustrating the PowerShell comparison operators. In this case, we don't intend the reader to copy and run this example. Notice that this example uses `PS>` as a simplified @@ -205,8 +205,8 @@ box frame on the web page. The **Output** code box has no syntax highlighting. ### Avoid line continuation in code samples -Avoid using line continuation characters (`` ` ``) in PowerShell code examples. These are hard to -see and can cause problems if there are extra spaces at the end of the line. +Avoid using line continuation characters (`` ` ``) in PowerShell code examples. Backtick characters +are difficult to see and can cause problems if there are extra spaces at the end of the line. - Use PowerShell [splatting][02] to reduce line length for cmdlets that have several parameters. - Take advantage of PowerShell's natural line break opportunities, like after pipe (`|`) characters, @@ -246,14 +246,14 @@ Cmdlet and parameter names must use the proper [Pascal-cased][06] names. ### Using parameters in examples -Avoid using positional parameters. In general, you should always include the parameter name in an -example, even if the parameter is positional. This reduces the chance of confusion in your examples. +Avoid using positional parameters. To reduce the chance of confusion, you should include the +parameter name in an example, even if the parameter is positional. ## Formatting cmdlet reference articles -Cmdlet reference articles have a specific structure. This structure is defined by [PlatyPS][07]. -PlatyPS generates the cmdlet help for PowerShell modules in Markdown. After editing the Markdown -files, PlatyPS is used create the MAML help files used by the `Get-Help` cmdlet. +Cmdlet reference articles have a specific structure. [PlatyPS][07] defines this structure. PlatyPS +generates the cmdlet help for PowerShell modules in Markdown. After you edit the Markdown files, +PlatyPS can create the MAML help files used by the `Get-Help` cmdlet. PlatyPS has a schema that expects a specific structure for cmdlet reference. The PlatyPS [schema document][08] describes this structure. Schema violations cause build errors that must be @@ -322,7 +322,7 @@ Basic formatting guidelines: ``` - Markdown tables - - For `About_*` topics, tables must fit within 76 characters + - For `About_*` articles, tables must fit within 76 characters - If the content doesn't fit within 76 character limit, use bullet lists instead - Use opening and closing `|` characters on each line diff --git a/reference/docs-conceptual/community/contributing/product-terminology.md b/reference/docs-conceptual/community/contributing/product-terminology.md index 8b0fa60ecadf..16491d9b1e31 100644 --- a/reference/docs-conceptual/community/contributing/product-terminology.md +++ b/reference/docs-conceptual/community/contributing/product-terminology.md @@ -1,13 +1,13 @@ --- description: This article contains guidelines for the proper use of product names and terms. -ms.date: 06/20/2024 +ms.date: 03/30/2025 title: Product terminology and branding guidelines --- # Product terminology and branding guidelines -When writing about any product it's important to correctly and consistently use product names and -terminology. This guide defines product names and terminology related to PowerShell. Note the -capitalization of specific words or use cases. +When you write about any product, it's important to use the proper product names and terminology. +This guide defines product names and terminology related to PowerShell. Note the capitalization of +specific words or use cases. ## PowerShell (collective name) @@ -15,8 +15,8 @@ Use **PowerShell** to describe the scripting language and an interactive shell. ### PowerShell (product name) -The cross-platform version of PowerShell that's built on .NET (core), rather than the .NET -Framework. PowerShell can be installed on Windows, Linux, and macOS. +The cross-platform version of PowerShell built on .NET (core), rather than the .NET Framework. +PowerShell can be installed on Windows, Linux, and macOS. ### PowerShell Core (product deprecated) @@ -89,15 +89,13 @@ since ASM is scheduled for retirement. These products are used to manage Azure resources but aren't part of the Azure PowerShell collective product. They should never be described using the "Azure PowerShell" collective name. -- Azure Active Directory PowerShell (AzureAD) - Azure Information Protection PowerShell - Azure Deployment Manager PowerShell - Azure Elastic Database Jobs PowerShell - Azure Service Fabric PowerShell - Azure Stack PowerShell -- Microsoft.Graph PowerShell -- Microsoft.Graph.Entra PowerShell -- MSOnline PowerShell +- Microsoft Graph PowerShell SDK +- Microsoft Entra PowerShell Guidelines diff --git a/reference/docs-conceptual/community/contributing/pull-requests.md b/reference/docs-conceptual/community/contributing/pull-requests.md index 0a1203ecfc01..f6c0dd8945d9 100644 --- a/reference/docs-conceptual/community/contributing/pull-requests.md +++ b/reference/docs-conceptual/community/contributing/pull-requests.md @@ -1,6 +1,6 @@ --- description: This article explains how to submit pull requests to the PowerShell-Docs repository. -ms.date: 07/26/2022 +ms.date: 03/30/2025 title: How to submit pull requests --- # How to submit pull requests @@ -38,12 +38,12 @@ changed files. Large PRs are difficult to review and are more prone to contain e ### Renaming or deleting files -When renaming or deleting files, there must be an issue associated with the PR. That issue must +There must be an issue associated with the PR when you rename or delete files. That issue must discuss the need to rename or delete the files. -Avoid mixing content additions or changes with file renames and deletes. Any file that's renamed or -deleted must be added to the global redirection file. When possible, update any files that link to -the renamed or deleted content, including any TOC files. +Avoid mixing content additions or changes with file renames and deletes. Any file that you rename or +delete must be added to the appropriate redirection file. When possible, update any files that link +to the renamed or deleted content, including any TOC files. ### Avoid editing repository configuration files @@ -65,9 +65,9 @@ configuration files are any files that match one or more of these patterns: - `ThirdPartyNotices` - `tools/**` -For safety and security, if you believe you have discovered a bug or potential improvement for a -repository configuration file, [file an issue][2]. The maintainers will review and implement any -fixes or improvements as needed. +For safety and security, don't change these files. If you think one of these files should be +changed, [file an issue][2]. After the maintainers triage the issue, they'll make the appropriate +changes. ## Use the PR template @@ -123,9 +123,9 @@ If your PR is a work-in-progress, set it to [draft mode][4] or prefix your PR ti ## Expectations Comment -After you submit your PR, a bot will comment on your PR to provide you with resources and to set -expectations for the rest of the process. Always review this comment, even if you've contributed -before, because it contains accurate and up-to-date information. +After you submit your PR, a bot will comment on your PR. The comment provides resources and sets +expectations for the rest of the process. We might update this comment periodically, so always +review the comment, even if this isn't your first contribution. ![example expectation comment][5] @@ -134,29 +134,27 @@ before, because it contains accurate and up-to-date information. The Docs PR validation service is a GitHub app that runs validation rules on your changes. You must fix any errors or warnings reported by the validation service. -You'll see the following behavior: +The following steps outline the validation behavior: 1. You submit a PR. -1. In the GitHub comment that indicates the status of your PR, you'll see the status of "checks" - enabled on the repository. In this example, there are two checks enabled, "Commit Validation" and - "OpenPublishing.Build": +1. In the GitHub comment that indicates the status of the "checks" enabled on the repository. In + this example, there are two checks enabled, "Commit Validation" and "OpenPublishing.Build": ![validation status - some checks failed][6] The build can pass even if commit validation fails. -1. Click **Details** for more information. -1. On the Details page, you'll see all the validation checks that failed, with information about how - to fix the issues. +1. Select **Details** for more information. The **Details** page shows all the validation checks + that failed and includes information about how to fix the issues. 1. When validation succeeds, the following comment is added to the PR: ![Validation status: success][7] > [!NOTE] -> If you are an external (not a Microsoft employee) contributor you don't have access to the +> If you're an external contributor (not a Microsoft employee), you don't have access to the > detailed build reports or preview links. -When the PR is reviewed, you may be asked to make changes or fix validation warning messages. The +When the PR is reviewed, you might be asked to make changes or fix validation warning messages. The PowerShell-Docs team can help you understand validation errors and editorial requirements. ## GitHub Actions @@ -166,14 +164,14 @@ and the reviewers. ### Checklist verification -If your PR is not in [draft mode][4] and is not prefixed with `WIP`, a GitHub Action inspects your -PR to verify that you have checked every item in the PR template's checklist. If this check fails, -the team won't review or merge your PR. The checklist items are mandatory. +If your PR isn't in [draft mode][4] and isn't prefixed with `WIP`, a GitHub Action inspects your PR +to verify that you selected every item in the PR template's checklist. The maintainers won't review +or merge your PR until you complete the checklist. The checklist items are mandatory. ### Authorization verification If your PR targets the `live` branch or modifies any repository configuration files, a GitHub Action -checks your permissions to verify that you are authorized to submit those changes. +checks your permissions to verify that you're authorized to submit those changes. Only repository administrators are authorized to target the `live` branch or modify repository configuration files. @@ -183,8 +181,7 @@ configuration files. If your PR adds, removes, or modifies any versioned content a GitHub Action analyzes your changes and writes a report summarizing the types of changes made to versioned content. -This report is useful for seeing if there are other versions of the file(s) you modified and whether -or not those versions have also been updated in the changeset. +This report can show if there are other versions of the files that you need to update in this PR. To find the versioned content report for your PR: diff --git a/reference/docs-conceptual/community/contributing/quality-improvements.md b/reference/docs-conceptual/community/contributing/quality-improvements.md index 19823e18c45f..ce35b60daaea 100644 --- a/reference/docs-conceptual/community/contributing/quality-improvements.md +++ b/reference/docs-conceptual/community/contributing/quality-improvements.md @@ -1,16 +1,15 @@ --- description: >- This article describes the process for contributing quality improvements to the documentation. -ms.date: 06/28/2023 +ms.date: 03/30/2025 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 continues and generalizes that process, providing a low-friction -way for community members to contribute and collaborate on GitHub through enhancing the quality of -documentation. +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. We're focusing on these quality areas: @@ -85,12 +84,12 @@ All code samples should follow the [style guidelines][03] for PowerShell content repeated in abbreviated form here for convenience: - All code blocks should be contained in a triple-backtick code fence (`` ``` ``). -- Line length for code blocks is limited to `90` characters except in About topics, where it's - limited to `76` characters. +- Line length for code blocks is limited to `90` characters for cmdlet reference articles. +- Line length for code blocks is limited to `76` characters for `about_*` articles. - Avoid using line continuation characters (`` ` ``) in PowerShell code examples. - Use splatting or natural line break opportunities, like after pipe (`|`) characters, opening braces (`}`), parentheses (`(`), and brackets (`[`) to limit line length. -- Only include the PowerShell prompt for illustrative examples where the code is not intended for +- Only include the PowerShell prompt for illustrative examples where the code isn't intended for copy-pasting. - Don't use aliases in examples unless you're specifically documenting the alias. - Avoid using positional parameters. Use the parameter name, even if the parameter is positional. @@ -109,9 +108,9 @@ here for convenience: - PowerShell module names should be **bold**. - PowerShell keywords and operators should be all lowercase. - Use proper (Pascal) casing for cmdlet names and parameters. -- When referring to a parameter by name, the name should be **bold**. When illustrating the use of - a parameter with the hyphen prefix, the parameter should be wrapped in backticks. -- When showing example usage of an external command, the example should be wrapped in backticks. +- When you refer to a parameter by name, the name should be **bold**. +- Use parameter name with the hyphen if you're illustrating syntax. Wrap the parameter in backticks. +- When you show example usage of an external command, the example should be wrapped in backticks. Always include the file extension of the external command. ## Link references @@ -134,7 +133,7 @@ The [Packages tab][31] 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 do this quickly. +> [reflow-markdown][30] VS Code extension to quickly reflow the paragraph. At the bottom of the file, add a markdown comment before the definition of the links. @@ -163,16 +162,14 @@ Make sure of the line lengths and use the [Reflow Markdown][30] extension to fix ## Spelling -Sometimes, despite our best efforts, typos and misspellings get through and end up in the -documentation. These 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. +Despite our best efforts, typos and misspellings get through and end up in the documentation. These +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. Once you've decided what articles and content areas you want to work on, follow these -steps: +to improve. Use the following steps to guide your work: @@ -200,7 +197,8 @@ steps: - resolves #123 ``` - The content developers will review your work as soon as they can to help you get it merged. + After you submit the PR, the maintainers will review your work and work with you to get it + merged. diff --git a/reference/docs-conceptual/community/contributing/using-github-codespaces.md b/reference/docs-conceptual/community/contributing/using-github-codespaces.md index 4796bb96fa6e..cdfa1f4b3688 100644 --- a/reference/docs-conceptual/community/contributing/using-github-codespaces.md +++ b/reference/docs-conceptual/community/contributing/using-github-codespaces.md @@ -2,7 +2,7 @@ description: >- This article describes the process for contributing to the documentation using GitHub Codespaces as an authoring environment. -ms.date: 05/10/2023 +ms.date: 03/30/2025 title: Contribute using GitHub Codespaces --- @@ -37,17 +37,15 @@ already available for you: ## Cost -GitHub Codespaces can be used for free up to 120 core-hours per month. With the configuration we -recommend in this article, that means up to 60 hours of free usage per month. The monthly usage is +GitHub Codespaces can be used for free up to 120 core-hours per month. The monthly usage is calculated across all your repositories, not just documentation. For more information about pricing, see [About billing for GitHub Codespaces][12]. > [!TIP] -> If you're comfortable using containers and Docker, you can get the same experience as using -> GitHub Codespaces in VS Code by using the devcontainer defined for the PowerShell documentation -> repositories. There's no cost associated with using devcontainers. For more information, see -> the [Dev Containers tutorial][13]. +> If you're comfortable using containers and Docker, you can get the same experience by using the +> devcontainer defined for the PowerShell documentation repositories. There's no cost associated +> with using devcontainers. For more information, see the [Dev Containers tutorial][13]. ## Creating your GitHub Codespace @@ -69,7 +67,7 @@ The UI is based on VS Code and works the same way. To open your GitHub Codespace in the browser, follow these steps: 1. Open [https://github.com/codespaces][14] in your browser. -1. The page lists your codespaces. Find the created codespace for the repository you want to +1. The page lists your Codespaces. Find the created codespace for the repository you want to contribute to and select it. After you select your codespace, GitHub opens it in the same window. From here, you're ready to @@ -91,15 +89,15 @@ writing or editing your contribution. When you want to turn an inline link, like `[some text](destination.md)`, into a reference link like `[some text][01]`, select the link destination in the editor. Then you can either: -1. Right click on the link destination and select "Refactor..." in the context menu. +1. Right-click on the link destination and select "Refactor..." in the context menu. 1. Press Ctrl+Shift+R. -Either action raises the refactoring context menu. Select "Extract to link definition" in the -context menu. This replaces the `(destination.md)` in the link with `[def]`. You can rename the +Either action raises the refactoring context menu. To replace the `(destination.md)` in the link +with `[def]`, select **Extract to link definition** in the context menu. You can rename the definition by typing a name in. For the PowerShell documentation, we use two-digit numerical reference link definitions, like -`[01]` or `[31]`. Only use reference link definitions in about topics and conceptual documentation. +`[01]` or `[31]`. Only use reference link definitions in about articles and conceptual documentation. Don't use reference link definitions in cmdlet reference documentation. ### Fix prose style violations @@ -110,8 +108,8 @@ document with colored squiggles. Hover over a violation to see more information about it. -Select the rule's name in the hover information to open a web page that explains the rule. Select -the rule's filename (ending in `.yml`) to open the rule and review its implementation. +To open a web page that explains the rule, select the rule's name in the hover information. To open +the rule and review its implementation, select the rule's filename (ending in `.yml`). If the rule supports a quick fix, you can select "Quick Fix..." in the hover information for the violation and apply one of the suggested fixes by selecting it from the context menu. You can also @@ -127,9 +125,8 @@ When you review an article in your codespace, Markdownlint automatically checks you open it and as you type. If Markdownlint finds any syntax problems, it highlights them in the document with colored squiggles. -Hover over a violation to see more information about it. - -Select the rule's ID in the hover information to open a web page that explains the rule. +Hover over a violation to see more information about it. To open a web page that explains the rule, +select the rule's ID in the hover information. If the rule supports a quick fix, you can select "Quick Fix..." in the hover information for the violation and apply one of the suggested fixes by selecting it from the context menu. You can also @@ -203,7 +200,7 @@ command. When you select that command, VS Code opens a preview of the active doc preview's style matches the Learn platform. > [!NOTE] -> Site-relative and cross-reference links won't work in the preview. +> Site-relative and cross-reference links don't work in the preview. ### Reflow your content @@ -216,9 +213,9 @@ When using this command for block quotes, make sure the paragraph in the block q reflowing is surrounded by blank lines. Otherwise, the command reflows every paragraph together. > [!CAUTION] -> Don't use this command when editing about topics. The lines in those documents must not be +> Don't use this command when editing about articles. The lines in those documents must not be > longer than 80 characters. There's currently no way for a repository to configure different line -> lengths by folder or filename, so reflow doesn't work for about topic documents. +> lengths by folder or filename, so reflow doesn't work for about article documents. ### Review all problems in a document diff --git a/reference/docs-conceptual/community/digital-art.md b/reference/docs-conceptual/community/digital-art.md index 508ce04f1a6a..69e5ff6ec114 100644 --- a/reference/docs-conceptual/community/digital-art.md +++ b/reference/docs-conceptual/community/digital-art.md @@ -2,7 +2,7 @@ author: sdwheeler description: Download PowerShell related artwork and posters ms.author: sewhee -ms.date: 06/28/2023 +ms.date: 03/30/2025 title: PowerShell Digital Art --- # PowerShell Digital Art