参与质量改进

对于 Hacktoberfest 2022，我们 试点了一个流程 ，用于为 PowerShell 内容提供质量改进。 本指南将定义低摩擦方法的过程通用化，以便社区成员提高文档质量。

我们专注于以下质量领域：

• 设置代码示例的格式
• 格式化命令语法
• 链接引用
• Markdown lint 分析
• 拼写

项目跟踪

我们通过 PowerShell Docs 质量贡献 GitHub 项目来跟踪贡献。

项目页具有与此工作相关的问题和 PR 的多个视图：

• “打开问题”视图显示所有打开的问题。
• “已完成”视图显示合并的 PR。
• PowerShell 视图显示 PowerShell-Docs、PowerShell-Docs-DSC 和 PowerShell-Docs-Modules 存储库中文档的开放问题。
• Windows PowerShell 视图显示了 windows-powershell-docs 存储库中的文档开放问题。
• Azure PowerShell 视图显示 azure-docs-powershell 存储库中与文档相关的开放问题。
• “打开 PR”视图显示所有打开的 PR。

设置代码示例的格式

所有代码示例都应遵循 PowerShell 内容的 样式准则 。 为了方便起见，此处以缩写形式重复这些规则：

• 所有代码块都应包含在三个反引号代码隔离区 (```) 中。
• 对于 cmdlet 参考文章，代码块的行长度限制为 90 个字符。
• 代码块的行长度仅限于 76 文章的 about_* 字符。
• 避免在 PowerShell 代码示例中使用行延续字符（`）。
  • 使用展开或自然换行机会，比如在竖线(|) 字符、左大括号 (})、圆括号 (() 和方括号 ([) 后使用，以便限制行长度。
• 仅在展示性示例中包含 PowerShell 提示符，这些代码不适合复制粘贴。
• 除非专门记录别名，否则不要在示例中使用别名。
• 避免使用位置参数。 使用参数名称，即使参数是位置。

格式命令语法

所有散文都应遵循 PowerShell 内容的 样式准则 。 为了方便起见，此处将重复这些规则：

• 始终使用命令行脚本和参数的完整名称。 除非是要专门演示别名，否则避免使用别名。
• 属性、参数、对象、类型名称、类名、类方法应为 粗体。
  • 属性和参数值应用反引号 (`) 引起来。
  • 在使用方括号样式引用类型时，请使用反引号。 例如：[System.Io.FileInfo]
• PowerShell 模块名称应 为粗体。
• PowerShell 关键字和运算符应全部小写。
• 对 cmdlet 名称和参数使用适当的 (Pascal) 大小写。
• 按名称引用参数时，名称应 为粗体。
• 如果要说明语法，请使用带连字符的参数名称。 使用反引号将参数引起来。
• 演示外部命令的示例用法时，示例应由反引号引起来。 务必包含外部命令的文件扩展名。

链接引用

为了保持文档的 Markdown 源的可维护性和可读性，我们将概念文档转换为使用链接引用，而不是内联链接。

例如，而不是：

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

它应为：

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

在文件的底部，在链接的定义前添加 markdown 注释。

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

请确保：

1. 链接按照它们在文档中显示的顺序定义。
2. 每个链接指向正确的位置。
3. 链接引用定义位于 markdown 注释之后的文件底部，并按正确的顺序排列。

Markdown lint 分析

对于其中一个参与存储库中的任何文章，在 VS Code 中打开文章将显示代码 lint 分析警告。 解决发现的任何警告，但以下内容除外：

• cmdlet 参考文档中的 标头的 Synopsis。 对于这些项目，规则违规是有意的，以确保文档能正确使用 PlatyPS 生成。

请确保行长度，并使用 Reflow Markdown 扩展修复任何长行。

拼写

尽管我们尽了最大努力，但打字错误和拼写错误还是会漏掉，最终出现在文档中。 这些错误使得文档难以遵循和本地化。 修复这些错误会使文档更具可读性，尤其是对于依赖准确翻译的非英语演讲者。

过程

我们鼓励你选择一个或多个质量区域以及一篇文章（或一组文章）进行改进。 使用以下步骤指导工作：

1. 检查项目中是否有针对这项工作提交的问题，以避免重复工作。

2. 在相应的存储库中打开新问题：

   • 在 MicrosoftDocs/PowerShell-Docs 中针对 PowerShell 参考和概念内容打开一个问题。
   • 在 MicrosoftDocs/PowerShell-Docs-Dsc 中为 DSC 内容提出问题
   • 在 MicrosoftDocs/PowerShell-Docs-Modules 中，为 Crescendo、PlatyPS、PSScriptAnalyzer、SecretManagement 和 SecretStore 内容提出问题。
   • 在 MicrosoftDocs/azure-docs-powershell 中为 Azure PowerShell 内容提出问题。
   • 在 适用于 Windows PowerShell 模块内容的 MicrosoftDocs/windows-powershell-docs 中 提出问题。

3. 按照我们的参与者指南为进行更改做好准备。

4. 提交拉取请求。 确保：

   1. PR 标题具有 Quality: 前缀。

   2. PR 正文将参考作为无序列表项解决的问题，并使用其中一个链接关键字。

      例如，如果正在处理问题 123，PR 正文应包括以下 Markdown：

      - resolves #123
      

   提交 PR 后，维护人员将评审你的工作，并与你合作，使其合并。