Contributing quality improvements

For Hacktoberfest 2022, we piloted a process 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.

We're focusing on these quality areas:

• Formatting code samples
• Formatting command syntax
• Link References
• Markdown linting
• Spelling

Project Tracking

We're tracking contributions with the PowerShell Docs Quality Contributions GitHub Project.

The project page has several views for the issues and PRs related to this effort:

• The Open issues view shows all open issues.
• The Completed view shows merged PRs.
• The PowerShell view shows open issues for documentation in the PowerShell-Docs, PowerShell-Docs-DSC, and PowerShell-Docs-Modules repositories.
• The Windows PowerShell view shows open issues for documentation in the windows-powershell-docs repository.
• The Azure PowerShell view shows open issues for documentation in the azure-docs-powershell repository.
• The Open PRs view shows all open PRs.

Formatting code samples

All code samples should follow the style guidelines 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 (```).
• 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 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.

Formatting command syntax

All prose should follow the style guidelines for PowerShell content. Those rules are repeated here for convenience:

• Always use the full name for cmdlets and parameters. Avoid using aliases unless you're specifically demonstrating the alias.
• Property, parameter, object, type names, class names, class methods should be bold.
  • Property and parameter values should be wrapped in backticks (`).
  • When referring to types using the bracketed style, use backticks. For example: [System.Io.FileInfo]
• PowerShell module names should be bold.
• PowerShell keywords and operators should be all lowercase.
• Use proper (Pascal) casing for cmdlet names and parameters.
• 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

For maintainability and readability of the markdown source for our documentation, we're converting our conceptual documentation to use link references instead of inline links.

For example, instead of:

The [Packages tab][31] displays all available
packages in the PowerShell Gallery.

It should be:

The [Packages tab][31] displays all available packages in the PowerShell Gallery.

At the bottom of the file, add a markdown comment before the definition of the links.

<!-- Link references -->
[01]: https://www.powershellgallery.com/packages

Make sure that:

1. The links are defined in the order they appear in the document.
2. Every link points to the correct location.
3. The link reference definitions are at the bottom of the file after the markdown comment and are in the correct 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 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 extension to fix any long lines.

Spelling

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. Use the following steps to guide your work:

1. Check the project for issues filed for this effort to avoid duplicating efforts.

2. Open a new issue in the appropriate repository:

   • Open an issue in MicrosoftDocs/PowerShell-Docs for PowerShell reference and conceptual content.
   • Open an issue in MicrosoftDocs/PowerShell-Docs-Dsc for DSC content
   • Open an issue in MicrosoftDocs/PowerShell-Docs-Modules for Crescendo, PlatyPS, PSScriptAnalyzer, SecretManagement, and SecretStore content.
   • Open an issue in MicrosoftDocs/azure-docs-powershell for Azure PowerShell content.
   • Open an issue in MicrosoftDocs/windows-powershell-docs for Windows PowerShell module content.

3. Follow our contributor's guide to get setup for making your changes.

4. Submit your pull request. Ensure:

   1. Your PR title has the Quality: prefix.

   2. Your PR body references the issue it resolves as an unordered list item and uses one of the linking keywords.

      For example, if you're working on issue 123, the body of your PR should include the following Markdown:

      - resolves #123
      

   After you submit the PR, the maintainers will review your work and work with you to get it merged.