Microsoft Docs 参与者指南概述Microsoft Docs contributor guide overview

欢迎查看 docs.microsoft.com (Docs) 参与者指南!Welcome to the docs.microsoft.com (Docs) Contributor Guide!

一些 Microsoft 文档集是托管在 GitHub 上的开源资源。Several of the Microsoft documentation sets are open source and hosted on GitHub. 并非所有文档集都是完全开放的资源,但许多文档集有面向公众的存储库,你可在其中通过拉取请求提交更改建议。Not all document sets are completely open source but many have public-facing repos where you can make suggested changes via pull requests. 这种开源方法简化了产品工程师、内容团队和客户之间的沟通流程,提高了效率,并实现了其他优势:This open source approach streamlines and improves communication between product engineers, content teams, and customers, and has other advantages:

  • 开源存储库以公开方式计划,通过反馈得知哪些文档的需求量最大__。Open source repos plan in the open to get feedback on what docs are most needed.
  • 开源存储库以公开方式评审,以便针对首个版本发布最具帮助意义的内容__。Open source repos review in the open to publish the most helpful content on our first release.
  • 开源存储库以公开方式更新,让我们能够更加方便地持续改进内容__。Open source repos update in the open to make it easier to continuously improve the content.

docs.microsoft.com 上的用户体验直接集成 GitHub 工作流,操作更简单。The user experience on docs.microsoft.com integrates GitHub workflows directly to make it even easier. 你可以从编辑正在查看的文档开始,Start by editing the document you are viewing. 也可以通过审查新主题创建质量问题来提供帮助。Or, help by reviewing new topics, or create quality issues.

重要

发布到 docs.microsoft.com 的所有存储库均遵循 Microsoft 开放源代码行为准则.NET 基础行为准则All repositories that publish to docs.microsoft.com have adopted the Microsoft Open Source Code of Conduct or the .NET Foundation Code of Conduct. 有关详细信息,请参阅行为准则常见问题解答For more information, see the Code of Conduct FAQ. 或如有任何疑问或意见,请联系 opencode@microsoft.comconduct@dotnetfoundation.orgOr contact opencode@microsoft.com, or conduct@dotnetfoundation.org with any questions or comments.

docs.microsoft.com 使用条款适用于对公共存储库中文档和代码示例所做的小修订和澄清。Minor corrections or clarifications to documentation and code examples in public repositories are covered by the docs.microsoft.com Terms of Use. 如果你不是 Microsoft 的员工,那么新内容或重大更改会在拉取请求中生成一条评论,要求你在线提交一份贡献许可协议 (CLA)。New or significant changes generate a comment in the pull request, asking you to submit an online Contribution License Agreement (CLA) if you are not an employee of Microsoft. 在我们评审或接受拉取请求之前,需要你填写这份在线表单。We need you to complete the online form before we can review or accept your pull request.

对现有文档进行快速编辑Quick edits to existing documents

快速编辑可简化报告并修复文档中的小错误和遗漏的过程。Quick edits streamline the process to report and fix small errors and omissions in documents. 尽管我们做出了各种各样的努力,我们发布的文档中仍可能出现小的语法错误和拼写错误__。Despite all efforts, small grammar and spelling errors do make their way into our published documents. 你可以通过创建问题来报告错误,但更加快捷和简单的做法是通过创建拉取请求来解决问题(如果创建拉取请求的选项可用)。While you can create issues to report mistakes, it's faster and easier to create a pull request (PR) to fix the issue, when the option is available.

  1. 你可以在浏览器中直接编辑某些文档页面的内容。Some docs pages allow you to edit content directly in the browser. 如果是这样,便会看到如下所示的“编辑”**** 按钮。If so, you'll see an Edit button like the one shown below. 单击“编辑”****(或等效的本地化名称)按钮将转到 GitHub 上的源文件。Clicking the Edit (or equivalently localized) button takes you to the source file on GitHub. 如果缺少“编辑”按钮,则意味着无法更改该文档页面****。If the Edit button is missing, that means the documentation page is not available to be changed.

    “编辑”链接的位置

  2. 接下来,单击铅笔图标来编辑文章,如下所示。Next, click the pencil icon, to edit the article as shown. 如果铅笔图标呈灰显,则你需要登录到 GitHub 帐户,或者创建一个新帐户。If the pencil icon is grayed out, you need to either log in to your GitHub account or create a new account.

    铅笔图标的位置

  3. 在 Web 编辑器中进行更改。Make your changes in the web editor. 这是使用称为“拉取请求”的操作来完成的。****Click the Preview changes tab to check the formatting of your change.

  4. 做出更改后,滚动到页面底部。Once you have made your changes, scroll to the bottom of the page. 为拉取请求输入标题和描述,并单击“建议文件更改”(Propose file change),如下图所示:****Enter a title and description for your changes and click Propose file change as shown in the following figure:

    建议文件更改

  5. 你已经提出更改,现在需要请求存储库的所有者将更改“拉取”到其存储库。Now that you've proposed your change, you need to ask the owners of the repository to "pull" your changes into their repository. 这是使用称为“拉取请求”的操作完成的。This is done using something called a "pull request". 单击上图中的“建议文件更改”时,你应该会进入一个如下图所示的新页面:****When you clicked on Propose file change in the figure above, you should have been taken to a new page that looks like the following figure:

    创建拉取请求

    单击“创建拉取请求”(Create pull request),为拉取请求输入标题(以及可选的描述),然后再次单击“创建拉取请求”。**** ****Click Create pull request, enter a title (and optionally a description) for the pull request, and then click Create pull request again. (如果不熟悉 GitHub,请参阅关于拉取请求,了解详细信息。)(If you are new to GitHub, see About Pull Requests for more information.)

  6. 就这么简单!That's it! 内容团队成员将评审并合并你的拉取请求。Content team members will review and merge your PR. 如果你进行了更大范围的更改,可能会收到一些请求更改的反馈。You may get some feedback requesting changes if you made larger changes.

GitHub 编辑界面会根据你在存储库上的权限做出响应。The GitHub editing UI responds to your permissions on the repository. 前面的图片适用于那些对目标存储库没有写入权限的参与者。The preceding images are accurate for contributors that do not have write permissions to the target repository. GitHub 会在你的帐户中自动创建目标存储库的一个分叉 (fork)。GitHub automatically creates a fork of the target repository in your account. 如果你有目标存储库的写入访问权限,GitHub 将在目标存储库中创建一个新分支 (branch)。If you have write-access to the target repository, GitHub creates a new branch in the target repo. 分支名称采用 <GitHubId>-patch-n 形式,使用的是你的 GitHub ID 和此修补程序分支的数字标识符****。The branch name has the form <GitHubId>-patch-n using your GitHub ID, and a numeric identifier for the patch branch.

我们使用拉取请求进行所有更改,即使更改来自于拥有写入权限的参与者,也不例外。We use pull requests for all changes, even for contributors that have write-access. 大多数存储库都保护 master 分支。这样一来,必须将更新提交为拉取请求。Most repositories have the master branch protected so that updates must be submitted as pull requests.

浏览器内编辑体验最适合进行细微或不频繁的更改。The in-browser editing experience is best for minor or infrequent changes. 如果你想贡献大量内容,或者使用高级 Git 功能(例如分支管理或高级合并冲突解决),则需要为存储库创建分叉,以便在本地工作If you make large contributions or use advanced Git features (such as branch management or advanced merge conflict resolution), you need to fork the repo and work locally.

备注

如果可用,你可以编辑一篇文章的任何语言版本,而且根据编辑的类型将出现以下情况:****If enabled, you can edit an article in any language and, based on the type of edit, the following will happen:

  1. 任何经过批准的语言更改也将用于帮助改进我们的机器翻译引擎any linguistic change that is approved, will also help improve our Machine Translation engine
  2. 任何显著修改文章内容的编辑都将在内部进行处理,以便针对同一文章的英语版本提交更改,从而在获得批准后,将编辑内容本地化为其他语言。any edit that significantly modifies the content of the article will be handled internally to submit a change to the same article in English so that it will get localized in all languages if approved. 你建议的改进不仅会给你自己语言的文章带来正面影响,还会影响其他所有可用语言。Your suggested improvements will not only positively affect articles in your own language, but in all available languages.

评审待定的拉取请求Review open PRs

在新主题发布之前,你可以通过检查当前待定的拉取请求来阅读它们。You can read new topics before they are published by checking the currently open PRs. 评审的过程遵循 GitHub 工作流Reviews follow the GitHub flow process. 你可以在公开存储库中看到建议的更新或新文章。You can see proposed updates or new articles in public repositories. 审阅这些内容并添加备注。Review them and add your comments. 请随意查看我们的文档存储库,并在你感兴趣的领域里查看待定的拉取请求。Look at any of our docs repositories, and check the open pull requests (PRs) for areas that interest you. 针对更新建议的社区反馈有益于整个社区。Community feedback on proposed updates helps the entire community.

创建质量问题Create quality issues

我们的文档需要持续完善。Our docs are a continuous work in progress. 高质量的问题反馈有助于我们将精力集中在社区的首要问题上。Good issues help us focus our efforts on the highest priorities for the community. 你提供的信息越详尽,问题反馈就越有帮助。The more detail you can provide, the more helpful the issue. 告诉我们你想获取的信息。Tell us what information you sought. 告诉我们你所用的搜索词。Tell us the search terms you used. 如果你不知从哪里入手,告诉我们你希望如何开始探索不熟悉的技术。If you can't get started, tell us how you want to start exploring unfamiliar technology.

许多 Microsoft 文档页的底部都有“反馈”**** 部分,可以单击此部分来提供“产品反馈”**** 或“内容反馈”****,以跟踪相应文章的具体问题。Many of Microsoft's documentation pages have a Feedback section at the bottom of the page where you can click to leave Product feedback or Content feedback to track issues that are specific to that article.

问题反馈可以开启关于所需内容的对话。Issues start the conversation about what's needed. 内容团队将对这些问题反馈作出回应,同时针对我们可以添加哪些内容表明自己的想法,并征求你的意见。The content team will respond to these issues with ideas for what we can add, and ask for your opinions. 当我们创建草稿时,会请求你对拉取请求进行评审When we create a draft, we'll ask you to review the PR.

更多地参与Get more involved

其他主题将帮助你高效地开始为 Microsoft Docs 贡献内容。它们介绍了如何使用 GitHub 存储库、Markdown 工具和 Microsoft Docs 平台中的扩展。Other topics help you get started productively contributing to Microsoft Docs. They explain working with GitHub repositories, Markdown tools, and extensions used in the Microsoft Docs platform.