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. すべてのドキュメント セットが完全にオープン ソースであるわけではありませんが、多くには一般公開用のリポジトリが備わっていて、そこで pull request を使って提案された変更を加えることができます。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. または、新しいトピックをレビューして支援するか、品質の Issue を作成しますOr, help by reviewing new topics, or create quality issues.

重要

docs.microsoft.com に公開されるすべてのリポジトリには、「Microsoft Open Source Code of Conduct」 (Microsoft オープン ソース倫理規定) または「.NET Foundation Code of Conduct」 (.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. 詳細については、「Code of Conduct FAQ」 (倫理規定に関する FAQ) を参照してください。For more information, see the Code of Conduct FAQ. または、ご質問やコメントがある場合は、opencode@microsoft.com または conduct@dotnetfoundation.org までご連絡ください。Or 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) の提出を要求するコメントが pull request 内に生成されます。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. pull request をレビューまたは承認できるように、オンライン フォームへのご記入をお願いいたします。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. 問題を作成して間違いを報告できますが、pull request (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 (pencil icon without text) 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 login 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. これで変更を提案したので、リポジトリの所有者に、変更をそのリポジトリに「pull」するように要求する必要があります。Now that you've proposed your change, you need to ask the owners of the repository to "pull" your changes into their repository. これを完了するには、「pull request」と呼ばれる作業を実行します。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:

    Pull request の作成

    [Create pull request](pull request の作成) をクリックして pull request のタイトル (および必要に応じて説明) を入力した後、もう一度 [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 を初めてお使いの場合、詳細については、「About Pull Requests」 (pull request について) を参照してください。)(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. ブランチ名には、GitHub ID、およびパッチのブランチに対する数値識別子を使用する、フォーム <GitHubId>-patch-n が含まれます。The branch name has the form <GitHubId>-patch-n using your GitHub ID, and a numeric identifier for the patch branch.

Microsoft では、書き込みアクセス権がある共同作成者も含めて、すべての変更に対して pull request を使用します。We use pull requests for all changes, even for contributors that have write-access. ほとんどのリポジトリに保護された master ブランチがあるため、更新を pull request として提出する必要があります。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. したがって、提案された改善は、自身の言語の記事を改善するだけでなく、利用可能なすべての言語に影響を与えます。So your suggested improvements will not only positively affect articles in your own language, but in all available languages.

開いている PR をレビューするReview 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. ドキュメント リポジトリのいずれかを参照し、関心のあるエリアの開いている pull requests (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.

品質の Issue を作成するCreate quality issues

Microsoft のドキュメントは、引き続き進行中の内容です。Our docs are a continuous work in progress. 適切な Issue は、Microsoft がコミュニティにとって優先度の高い内容に注力するために役立ちます。Good issues help us focus our efforts on the highest priorities for the community. 詳細を提供すればするほど、Issue の役に立ちます。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.

Issue により、必要な内容についての会話が始まります。Issues start the conversation about what's needed. コンテンツ チームは、追加できる内容のアイデアを用いて、これらの Issue に対応し、ご意見を伺います。The content team will respond to these issues with ideas for what we can add, and ask for your opinions. Microsoft でドラフトを作成した場合、お客様に PR のレビューを依頼します。When we create a draft, we'll ask you to review the PR.

深く関わるGet more involved

その他のトピックは、Microsoft Docs で生産的に投稿を開始するのに役立ちます。これらのトピックでは、Microsoft Docs プラットフォームで使用される GitHub リポジトリ、Markdown ツール、拡張機能の使い方について説明します。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.