Microsoft Docs 参与者指南概述

欢迎查看 docs.microsoft.com (Docs) 参与者指南!

一些 Microsoft 文档集是托管在 GitHub 上的开源资源。 并非所有文档集都是完全开放的资源,但许多文档集有面向公众的存储库,你可在其中通过拉取请求提交更改建议。 这种开源方法简化了产品工程师、内容团队和客户之间的沟通流程,提高了效率,并实现了其他优势:

  • 开源存储库以公开方式计划,通过反馈得知哪些文档的需求量最大
  • 开源存储库以公开方式评审,以便针对首个版本发布最具帮助意义的内容
  • 开源存储库以公开方式更新,让我们能够更加方便地持续改进内容

docs.microsoft.com 上的用户体验直接集成 GitHub 工作流,操作更简单。 你可以从编辑正在查看的文档开始, 也可以通过审查新主题创建质量问题来提供帮助。

重要

发布到 docs.microsoft.com 的所有存储库均遵循 Microsoft 开放源代码行为准则.NET 基础行为准则。 有关详细信息,请参阅行为准则常见问题解答。 或如有任何疑问或意见,请联系 opencode@microsoft.comconduct@dotnetfoundation.org

docs.microsoft.com 使用条款适用于对公共存储库中文档和代码示例所做的小修订和澄清。 如果你不是 Microsoft 的员工,那么新内容或重大更改会在拉取请求中生成一条评论,要求你在线提交一份贡献许可协议 (CLA)。 在我们评审或接受拉取请求之前,需要你填写这份在线表单。

对现有文档进行快速编辑

快速编辑可简化报告并修复文档中的小错误和遗漏的过程。 尽管我们做出了各种各样的努力,我们发布的文档中仍可能出现小的语法错误和拼写错误。 你可以通过创建问题来报告错误,但更加快捷和简单的做法是通过创建拉取请求来解决问题(如果创建拉取请求的选项可用)。

  1. 一些文档页面允许直接在浏览器中编辑内容。 如果是这样,便会看到如下所示的“编辑”按钮。 单击“编辑”(或等效的本地化名称)按钮将转到 GitHub 上的源文件。 如果缺少“编辑”按钮,则意味着无法更改该文档页面

    “编辑”链接的位置

    如果“编辑”按钮没有出现,则表示内容不向公众开放,公众无法贡献内容。

  2. 选择铅笔图标编辑文章。 如果铅笔图标呈灰显,则你需要登录到 GitHub 帐户,或者创建一个新帐户。

    铅笔图标的位置

  3. 在 Web 编辑器中进行更改。 这是使用称为“拉取请求”的操作来完成的。

  4. 做出更改后,滚动到页面底部。 为拉取请求输入标题和描述,并单击“建议文件更改”(Propose file change),如下图所示:

    建议文件更改

  5. 你已经提出更改,现在需要请求存储库的所有者将更改“拉取”到其存储库。 这是使用称为“拉取请求”的操作完成的。 选择“建议文件更改”后,会显示如下所示的新页:

    创建拉取请求

    选择“创建拉取请求”,为拉取请求输入标题和描述(可选),然后再次选择“创建拉取请求” 。 如果不熟悉 GitHub,请参阅拉取请求介绍了解详细信息。

  6. 就这么简单! 当 PR 获得批准后,内容团队成员会进行评审与合并。 你可能会收到要求进行更改的反馈。

GitHub 编辑界面会根据你在存储库上的权限做出响应。 前面的图片适用于那些对目标存储库没有写入权限的参与者。 GitHub 会在你的帐户中自动创建目标存储库的一个分叉 (fork)。 如果你有目标存储库的写入访问权限,GitHub 将在目标存储库中创建一个新分支 (branch)。 分支名称采用 GitHubId>-patch-n 形式,使用的是你的 GitHub ID 和此修改分支的数字标识符。

我们使用拉取请求进行所有更改,即使是拥有写权限的参与者,也不例外。 大多数存储库都保护默认分支。这样一来,必须将更新提交为拉取请求。

浏览器内编辑体验最适合进行细微或不频繁的更改。 如果你想贡献大量内容,或者使用高级 Git 功能(例如分支管理或高级合并冲突解决),则需要为存储库创建分叉,以便在本地工作

注意

大多数本地化文档不提供通过 GitHub 编辑或提供反馈的功能。 若要提供有关本地化内容的反馈,请使用 aka.ms/DocSiteLocFeedback 处提供的电子邮件模板。 Azure 文档有一个例外。 有用于 azure-docs 的公共本地化 GitHub 存储库可接受 6 种语言的社区贡献:简体中文、法语、德语、日语、韩语和西班牙语。 对于所有其他语言和内容集,请使用电子邮件模板(接收以任何语言输入)来报告翻译问题或提供技术反馈。

评审待定的拉取请求

在新主题发布之前,你可以通过检查当前待定的拉取请求来阅读它们。 评审的过程遵循 GitHub 工作流。 你可以在公开存储库中看到建议的更新或新文章。 审阅这些内容并添加备注。 请随意查看我们的文档存储库,并在你感兴趣的领域里查看待定的拉取请求。 针对更新建议的社区反馈有益于整个社区。

创建质量问题

我们的文档需要持续完善。 高质量的问题反馈有助于我们将精力集中在社区的首要问题上。 你提供的信息越详尽,问题反馈就越有帮助。 告诉我们你想获取的信息。 告诉我们你所用的搜索词。 如果你不知从哪里入手,告诉我们你希望如何开始探索不熟悉的技术。

许多 Microsoft 文档页的底部都有“反馈”部分,可以单击此部分来提供“产品反馈”或“内容反馈”,以跟踪相应文章的具体问题。

问题反馈可以开启关于所需内容的对话。 内容团队将对这些问题反馈作出回应,同时针对我们可以添加哪些内容表明自己的想法,并征求你的意见。 当我们创建草稿时,会请求你对拉取请求进行评审

更多地参与

其他主题将帮助你高效地开始为 Microsoft Docs 贡献内容。它们介绍了如何使用 GitHub 存储库、Markdown 工具和 Microsoft Docs 平台中的扩展。