Microsoft Docs 参与者指南概述

欢迎查看 Microsoft Docs 参与者指南!

在 Microsoft Learn 上与他人共享专业知识有助于每个人实现更多成就。 使用本指南中的信息将新文章发布到 Microsoft Learn 或更新现有已发布的文章。

在 Learn 上与他人共享专业知识有助于每个人实现更多成就。 使用本指南中的信息将新文章发布到 learn.microsoft.com 或更新已发布的文章。

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

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

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

重要

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

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

对文档进行快速编辑

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

  1. 一些文档页面允许直接在浏览器中编辑内容。 如果是这样,便会看到如下所示的“编辑”按钮。 选择“编辑”(或等效的本地化名称)按钮将转到 GitHub 上的源文件。

    编辑文章链接的位置。

    如果没有出现“编辑”按钮,则表示内容并未开放,公众无法贡献内容。 会生成一些页面(例如,从代码中的内联文档中生成),并且必须在这些页面所属的项目中编辑它们。

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

    分支和编辑铅笔图标的位置。

  3. 在 Web 编辑器中编辑文件。 选择“预览”选项卡来检查更改的格式。

  4. 完成编辑后,滚动到页面底部。 在“建议更改”区域,输入更改的标题和(可选)描述。 标题将是提交消息的第一行。 选择“建议更改”以提交更改:

    建议并提交文件更改。

  5. 提出并提交更改后,需要让存储库的所有者将更改“拉取”到其存储库。 这是使用称为“拉取请求”(PR) 的操作完成的。 选择“建议更改”后,会显示如下所示的新页:

    比较更改并创建拉取请求。

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

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

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

我们使用 PR 进行所有更改,即使对于具有写入访问权限的参与者也是如此。 大多数存储库都会为默认分支提供保护,使更新必须作为 PR 提交。

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

注意

大多数本地化文档不提供通过 GitHub 编辑或提供反馈的功能。 若要提供有关本地化内容的反馈,请使用 aka.ms/DocSiteLocFeedback 处提供的电子邮件模板。

评审待定的拉取请求

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

创建质量问题

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

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

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

更多地参与

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