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 Foundation 管理辦法 (英文)。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. 儘管您可以建立問題來回報錯誤,建立提取要求 (PR) 來解決問題會更加快速且輕鬆 (當該選項可用時)。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. 為變更的內容輸入標題與說明,然後按一下 [建議檔案變更],如下圖所示: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". 按一下上圖中的 [Propose file change] (建議檔案變更) 後,應該就會前往如下圖所示的新網面: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:

    建立提取要求

    按一下 [建立提取要求] 並輸入提取要求的標題 (也可以選擇輸入描述),然後再按一下 [建立提取要求]。Click Create pull request, enter a title (and optionally a description) for the pull request, and then click Create pull request again. (如果您沒有使用過 GitHub,請參閱 About Pull Requests (關於提取要求) 以取得詳細資訊。)(If you are new to GitHub, see About Pull Requests for more information.)

  6. 大功告成!That's it! 內容小組成員將檢閱並合併您的 PR。Content team members will review and merge your PR. 如果您做出較大規模的變更,則可能會收到一些要求變更的意見反應。You may get some feedback requesting changes if you made larger changes.

GitHub 編輯 UI 會回應您對存放庫的權限。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 會自動在您的帳戶中建立目標存放庫的分叉。GitHub automatically creates a fork of the target repository in your account. 如果您有目標存放庫的寫入權限,GitHub 會在目標存放庫中建立一個新的分支。If you have write-access to the target repository, GitHub creates a new branch in the target repo. 分支名稱的格式為 <GitHubId>-patch-n,並使用您的 GitHub 識別碼,以及針對修補分支的數值識別碼。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.

檢閱未處理的 PRReview open PRs

您可以透過查看目前未處理的 PR,來在新主題發佈之前閱讀它們。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. 查看我們的文件存放庫,並針對您感興趣的領域查看未處理的提取要求 (PR)。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. 當我們建立草稿時,我們會要求您檢閱 PRWhen 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.