开始为 PowerShell 文档做贡献

本文概述了如何入门成为 PowerShell 文档的贡献者。

PowerShell-Docs 结构

PowerShell-Docs 存储库中有三类内容：

• 引用内容
• 概念内容
• 元数据和配置文件

参考内容

参考内容是适用于 PowerShell 中附带的 cmdlet 的 PowerShell cmdlet 引用。 cmdlet 参考 存放在按版本分类的文件夹中（例如 5.1、7.4、7.5 和 7.6），这些文件夹包含随 PowerShell 一起发布的模块的参考资料。 此内容还用于创建由 Get-Help cmdlet 显示的帮助信息。

概念内容

概念文档 未按版本进行组织。 所有文章都针对每个版本的 PowerShell 显示。

元数据文件

此项目包含多种类型的元数据文件。 元数据文件控制生成工具和发布系统的行为。 仅允许 PowerShell-Docs 维护者和已批准的参与者更改这些文件。 如果认为应该更改元文件，请提出一个问题来讨论所需的更改。

存储库根目录中的元文件

• .* - 存储库根目录中的配置文件
• *.md - 存储库根目录中的项目文档
• *.yml - 存储库根目录中的项目文档
• .devcontainer/* - devcontainer 配置文件
• .github/**/* - GitHub 模板、操作和其他元文件
• .vscode/**/* - VS Code 扩展配置
• assets/* - 包含文档中链接的可下载文件
• redir/* - 包含重定向映射文件
• tests/* - 生成系统使用的测试工具
• tools/* - 生成系统使用的其他工具

文档集中的元文件

• reference/**/*.json - docset 配置文件
• reference/**/*.yml - TOC 和其他结构化内容文件
• reference/bread/* - 痕迹导航导航配置
• reference/includes/* - markdown 包含文件
• reference/mapping/* - 版本映射配置
• reference/**/media/** - 文档中使用的图像文件
• reference/module/* - 模块浏览器页面配置

创建新文章

必须为您要提交的任何新文档创建一个 GitHub 问题。 检查是否存在现有问题，确保不会重复工作。 被分配的问题被视为 in progress。 如果要协作处理问题，请联系分配给问题的人员。

与 PowerShell RFC 进程类似，请在编写内容之前创建问题。 此问题可确保你不会浪费时间和精力处理被 PowerShell-Docs 团队拒绝的工作。 此问题让我们能够与您讨论内容的范围及其在 PowerShell 文档中适合的位置。 所有文章都必须包含在目录 （TOC） 中。 建议的 TOC 位置应包含在问题讨论中。

更新现有文章

在适用的情况下，此存储库中维护的所有 PowerShell 版本都会重复 cmdlet 参考文章。 报告有关 cmdlet 引用或 About_ 项目的问题时，请列出有问题的项目版本。

对文件的每个版本应用适当的更改。

本地化内容

PowerShell 文档是用英语编写的，翻译为 17 种语言。 英语内容存储在名为 MicrosoftDocs/PowerShell-Docs的 GitHub 存储库中。 翻译内容中发现的问题应提交到此存储库。

所有翻译首先从英语内容开始。 我们同时使用人工翻译和机器翻译。

机器翻译翻译的内容并不总是会导致正确的单词选择和语法。 如果发现任何语言的翻译错误，而不是在文章的技术详细信息中，请提出一个问题，说明你认为翻译错误的原因。

可以通过更改英语源文件来修复某些翻译问题。 但是，某些问题可能需要更新内部翻译系统。 对于这些情况，我们必须将问题提交到内部本地化团队进行评审和响应。

后续步骤

在 GitHub 中提交更改有两种常见方法。 这两种方法都在中央参与者指南中介绍：

1. 可以在 GitHub Web 界面中对现有文档进行快速编辑。
2. 使用 完整的 GitHub 工作流 添加新文章、更新多个文件或其他大型更改。

在开始任何更改之前，应创建 PowerShell-Docs 存储库的分支。 应在 PowerShell-Docs 副本的工作分支中进行更改。如果在 GitHub 中使用 快速编辑 方法，将为你处理这些步骤。 如果使用完整的 GitHub 工作流，则必须设置为在本地工作。

这两种方法都以创建拉取请求 (PR) 结尾。 有关详细信息和最佳做法，请参阅 提交拉取请求。