通过

参与质量改进

你不必是主题专家或文档专家才能参与。 如果您发现改进文档的机会，请提交包含您建议的改进的拉取请求。 本指南概述了任何人都可以为文档提供质量改进的几种简单方法。

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

设置代码示例的格式

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

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

格式命令语法

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

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

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

例如，而不是：

The [Packages tab](https://www.powershellgallery.com/packages) displays all available
packages in the PowerShell Gallery.

它应为：

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

注释

替换内联链接时，请将内容重排，使每行不超过 100 个字符。 可以使用 reflow-markdown VS Code 扩展来快速重排段落。

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

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

请确保：

  1. 每个链接指向正确的位置。
  2. 不要重复链接引用定义。 如果 URL 已存在链接引用定义，请重复使用现有引用，而不是创建新的引用。
  3. 链接引用定义位于 markdown 注释之后的文件底部，并按数字顺序排列。

Markdown lint 分析

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

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

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

拼写

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

  • Last updated on