🎃 Hacktoberfest 2022

[michaeltlombardi]

This is the meta-issue for Hacktoberfest 2022 and the PowerShell content on Learn. For the month of October, we're focusing on providing a low-friction way for community members to contribute and collaborate on GitHub through enhancing the quality of documentation.

This Hacktober, we're focusing on the following quality areas:

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

Project Tracking

This Hacktober, we're tracking participation with the PowerShell Docs Hacktoberfest 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.

Aliases

We're working through documenting the aliases for every cmdlet.

In the Notes section, add the information to the beginning of the section using this format:

PowerShell includes the following aliases for `<Cmdlet-Name>`:

- All platforms:
  - `<alias>`
- Linux:
  - `<alias>`
- macOS:
  - `<alias>`
- Windows:
  - `<alias>`

If there is more than one alias for a platform, add it on a separate line as a new list item. If a platform has no aliases, omit it from the list.

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 except in About topics, where it's limited to 76 characters.
• 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 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 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. 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](https://www.powershellgallery.com/packages) displays all available packages in
the PowerShell Gallery.

It should be:

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 VS Code extension to do this quickly.

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 now of the line lengths and use the Reflow Markdown extension to fix any long lines.

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.

Process

You're encouraged 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:

1. Check this issue's history 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. The content developers will review your work as soon as they can to help you get it incorporated.

[chadmando]

Question on the Link References. I was looking at some of the conceptual content and the links are structured as references, but they use a short description instead of a numerical reference.

E.g. Short Description

- For older versions of Windows, see [RSAT for Windows][RSAT for Windows].

<!-- link references -->
[RSAT for Windows]: https://support.microsoft.com/help/2693643

Are you looking to change these to a numerical reference like this?

- For older versions of Windows, see [RSAT for Windows][01].

<!-- link references -->
[01]: https://support.microsoft.com/help/2693643

Or are you trying to clean up any documents that don't use the Link Reference structure?

[michaeltlombardi]

Great question, @chadmando!

We're looking to migrate everything consistently to numerical references. If they're using inline links, those should convert to numerical reference links. If they're using short description reference links, those should convert to numerical reference links.

The short description reference links are an artifact from when we started exploring migrating away from inline links.

[chadmando]

@michaeltlombardi Should image links be included in the link reference refactoring? I assume they fall into the scope of... "If they're using inline links, those should convert to numerical reference links."

[sdwheeler]

Hacktoberfest is over but we will still take contributions based on this issue.