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. または、新しいトピックをレビューして支援するか、品質に関するイシューを作成します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. 詳細については、倫理規定に関する 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](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. ブランチ名は <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.

書き込みアクセス権がある共同作成者の場合も、すべての変更に対して pull request が使われます。We use pull requests for all changes, even for contributors that have write-access. 更新が必ず pull request として提出されるように、ほとんどのリポジトリでは 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. 承認された言語的な変更は、Microsoft の機械翻訳エンジンの改善にも役立てられます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.

品質に関するイシューを作成するCreate quality issues

Microsoft のドキュメントは、進行中の継続的な作業です。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. ドラフトを作成し次第、お客様に 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.