11---
22description : >-
33 This article describes the process for contributing quality improvements to the documentation.
4- ms.date : 03/30/2025
4+ ms.date : 02/12/2026
55title : Contributing quality improvements
66---
77
88# Contributing quality improvements
99
10- For [ Hacktoberfest 2022] [ 31 ] , we [ piloted a process] [ 19 ] for contributing quality improvements to
11- the PowerShell content. This guide generalizes that process to define a low-friction way for
12- community members to improve to the quality of the documentation.
10+ You don't have to be a subject matter expert or a documentation expert to contribute. If you see an
11+ opportunity to improve the documentation, submit a pull request with your proposed improvement. This
12+ guide outlines several simple ways that anyone can contribute quality improvements to the
13+ documentation.
1314
1415We're focusing on these quality areas:
1516
16- <!-- - [Aliases][04] -->
17- - [ Formatting code samples] [ 05 ]
18- - [ Formatting command syntax] [ 06 ]
19- - [ Link References] [ 07 ]
20- - [ Markdown linting] [ 08 ]
21- - [ Spelling] [ 09 ]
17+ - [ Formatting code samples] [ 03 ]
18+ - [ Formatting command syntax] [ 04 ]
19+ - [ Link References] [ 05 ]
20+ - [ Markdown linting] [ 06 ]
21+ - [ Spelling] [ 07 ]
2222
23- ## Project Tracking
24-
25- We're tracking contributions with the [ PowerShell Docs Quality Contributions] [ 23 ] GitHub Project.
26-
27- The project page has several views for the issues and PRs related to this effort:
28-
29- <!-- markdownlint-disable MD044 -->
30-
31- - The [ Open issues] [ 24 ] view shows all open issues.
32- - The [ Completed] [ 25 ] view shows merged PRs.
33- - The [ PowerShell] [ 26 ] view shows open issues for documentation in the [ PowerShell-Docs] [ 14 ] ,
34- [ PowerShell-Docs-DSC] [ 15 ] , and [ PowerShell-Docs-Modules] [ 17 ] repositories.
35- - The [ Windows PowerShell] [ 27 ] view shows open issues for documentation in the
36- [ windows-powershell-docs repository] [ 21 ] .
37- - The [ Azure PowerShell] [ 28 ] view shows open issues for documentation in the
38- [ azure-docs-powershell repository] [ 12 ] .
39- - The [ Open PRs] [ 29 ] view shows all open PRs.
40-
41- <!-- markdownlint-enable MD044 -->
42-
43- <!-- ## Aliases
44-
45- We're working through documenting the aliases for every cmdlet.
46-
47- In the Notes section, add the information to the beginning of the section using this format:
48-
49- ```md
50- PowerShell includes the following aliases for `<Cmdlet-Name>`:
51-
52- - All platforms:
53- - `<alias>`
54- - Linux:
55- - `<alias>`
56- - macOS:
57- - `<alias>`
58- - Windows:
59- - `<alias>`
60- ```
61-
62- If there is more than one alias for a platform, add it on a separate line as a new list item. If a
63- platform has no aliases, omit it from the list.
64-
65- For Windows PowerShell, use one of these formats instead:
66-
67- 1. When the cmdlet has at least one alias
68-
69- ```md
70- Windows PowerShell includes the following aliases for `<Cmdlet-Name>`:
71-
72- - `<alias>`
73- ```
74-
75- 1. When the cmdlet haas no aliases
76-
77- ```md
78- Windows PowerShell includes no aliases for `<Cmdlet-Name>`.
79- ```
80- -->
8123## Formatting code samples
8224
83- All code samples should follow the [ style guidelines] [ 03 ] for PowerShell content. Those rules are
25+ All code samples should follow the [ style guidelines] [ 02 ] for PowerShell content. Those rules are
8426repeated in abbreviated form here for convenience:
8527
8628- 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.
12163For example, instead of:
12264
12365``` md
124- The [ Packages tab] [ 31 ] displays all available
66+ The [ Packages tab] ( https://www.powershellgallery.com/packages ) displays all available
12567packages in the PowerShell Gallery.
12668```
12769
12870It should be:
12971
13072``` md
131- The [ Packages tab] [ 31 ] displays all available packages in the PowerShell Gallery.
73+ The [ Packages tab] [ 01 ] displays all available packages in the PowerShell Gallery.
13274```
13375
13476> [ !NOTE]
13577> When you replace an inline link, reflow the content to wrap at 100 characters. You can use the
136- > [ reflow-markdown] [ 30 ] VS Code extension to quickly reflow the paragraph.
78+ > [ reflow-markdown] [ 09 ] VS Code extension to quickly reflow the paragraph.
13779
13880At the bottom of the file, add a markdown comment before the definition of the links.
13981
@@ -144,93 +86,35 @@ At the bottom of the file, add a markdown comment before the definition of the l
14486
14587Make sure that:
14688
147- 1 . The links are defined in the order they appear in the document.
148891 . Every link points to the correct location.
90+ 1 . Don't duplicate link reference definitions. If a link reference definition already exists for a
91+ URL, reuse the existing reference instead of creating a new one.
149921 . The link reference definitions are at the bottom of the file after the markdown comment and are
150- in the correct order.
93+ in the numeric order.
15194
15295## Markdown linting
15396
15497For any article in one of the participating repositories, opening the article in VS Code displays
15598linting warnings. Address any of these warnings you find, except:
15699
157- - [ MD022/blanks-around-headings/blanks-around-headers] [ 11 ] for the ` Synopsis ` header in cmdlet
100+ - [ MD022/blanks-around-headings/blanks-around-headers] [ 08 ] for the ` Synopsis ` header in cmdlet
158101 reference documents. For those items, the rule violation is intentional to ensure the
159102 documentation builds correctly with PlatyPS.
160103
161- Make sure of the line lengths and use the [ Reflow Markdown] [ 30 ] extension to fix any long lines.
104+ Make sure of the line lengths and use the [ Reflow Markdown] [ 09 ] extension to fix any long lines.
162105
163106## Spelling
164107
165108Despite our best efforts, typos and misspellings get through and end up in the documentation. These
166109mistakes make documentation harder to follow and localize. Fixing these mistakes makes the
167110documentation more readable, especially for non-English speakers who rely on accurate translations.
168111
169- ## Process
170-
171- We encourage you to choose one or more of the quality areas and an article (or group of articles)
172- to improve. Use the following steps to guide your work:
173-
174- <!-- markdownlint-disable MD044 -->
175-
176- 1 . Check the [ project] [ 23 ] for issues filed for this effort to avoid duplicating efforts.
177- 1 . Open a new issue in the appropriate repository:
178- - Open an issue in [ MicrosoftDocs/PowerShell-Docs] [ 20 ] for PowerShell reference and conceptual
179- content.
180- - Open an issue in [ MicrosoftDocs/PowerShell-Docs-Dsc] [ 16 ] for DSC content
181- - Open an issue in [ MicrosoftDocs/PowerShell-Docs-Modules] [ 18 ] for Crescendo, PlatyPS,
182- PSScriptAnalyzer, SecretManagement, and SecretStore content.
183- - Open an issue in [ MicrosoftDocs/azure-docs-powershell] [ 13 ] for Azure PowerShell content.
184- - Open an issue in [ MicrosoftDocs/windows-powershell-docs] [ 22 ] for Windows PowerShell module
185- content.
186- 1 . Follow our [ contributor's guide] [ 01 ] to get setup for making your changes.
187- 1 . Submit your pull request. Ensure:
188-
189- 1 . Your PR title has the ` Quality: ` prefix.
190- 1 . Your PR body references the issue it resolves as an unordered list item and uses one of the
191- [ linking keywords] [ 10 ] .
192-
193- For example, if you're working on issue ` 123 ` , the body of your PR should include the
194- following Markdown:
195-
196- ``` md
197- - resolves #123
198- ```
199-
200- After you submit the PR, the maintainers will review your work and work with you to get it
201- merged.
202-
203- <!-- markdownlint-enable MD044 -->
204-
205112<!-- Link References -->
206- [ 01 ] : /powershell/scripting/community/contributing/overview#prepare-to-make-a-contribution
207- [ 02 ] : /powershell/scripting/community/contributing/powershell-style-guide#formatting-command-syntax-elements
208- [ 03 ] : /powershell/scripting/community/contributing/powershell-style-guide#markdown-for-code-samples
209- <!-- [04]: #aliases -->
210- [ 05 ] : #formatting-code-samples
211- [ 06 ] : #formatting-command-syntax
212- [ 07 ] : #link-references
213- [ 08 ] : #markdown-linting
214- [ 09 ] : #spelling
215- [ 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
216- [ 11 ] : https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md022
217- [ 12 ] : https://github.com/MicrosoftDocs/azure-docs-powershell
218- [ 13 ] : https://github.com/MicrosoftDocs/azure-docs-powershell/issues/new?template=02-quality.yml&title=Quality%3A+
219- [ 14 ] : https://github.com/MicrosoftDocs/PowerShell-Docs
220- [ 15 ] : https://github.com/MicrosoftDocs/PowerShell-Docs-Dsc
221- [ 16 ] : https://github.com/MicrosoftDocs/PowerShell-Docs-Dsc/issues/new?template=02-quality.yml&title=Quality%3A+
222- [ 17 ] : https://github.com/MicrosoftDocs/PowerShell-Docs-Modules
223- [ 18 ] : https://github.com/MicrosoftDocs/PowerShell-Docs-Modules/issues/new?template=02-quality.yml&title=Quality%3A+
224- [ 19 ] : https://github.com/MicrosoftDocs/PowerShell-Docs/issues/9257
225- [ 20 ] : https://github.com/MicrosoftDocs/PowerShell-Docs/issues/new?template=02-quality.yml&title=Quality%3A+
226- [ 21 ] : https://github.com/MicrosoftDocs/windows-powershell-docs
227- [ 22 ] : https://github.com/MicrosoftDocs/windows-powershell-docs/issues/new?template=02-quality.yml&title=Quality%3A+
228- [ 23 ] : https://github.com/orgs/MicrosoftDocs/projects/15
229- [ 24 ] : https://github.com/orgs/MicrosoftDocs/projects/15/views/1
230- [ 25 ] : https://github.com/orgs/MicrosoftDocs/projects/15/views/2
231- [ 26 ] : https://github.com/orgs/MicrosoftDocs/projects/15/views/3
232- [ 27 ] : https://github.com/orgs/MicrosoftDocs/projects/15/views/4
233- [ 28 ] : https://github.com/orgs/MicrosoftDocs/projects/15/views/5
234- [ 29 ] : https://github.com/orgs/MicrosoftDocs/projects/15/views/6
235- [ 30 ] : https://marketplace.visualstudio.com/items?itemName=marvhen.reflow-markdown
236- [ 31 ] : https://www.powershellgallery.com/packages
113+ [ 02 ] : powershell-style-guide.md#markdown-for-code-samples
114+ [ 03 ] : #formatting-code-samples
115+ [ 04 ] : #formatting-command-syntax
116+ [ 05 ] : #link-references
117+ [ 06 ] : #markdown-linting
118+ [ 07 ] : #spelling
119+ [ 08 ] : https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md022
120+ [ 09 ] : https://marketplace.visualstudio.com/items?itemName=marvhen.reflow-markdown
0 commit comments