しかし今では、名も知らぬ誰かを呪う前に有効な選択肢があります。GitHub でPull Requestを送り、自分でドキュメントを修正する事が可能になってきています。
最近この修正を行う機会があり、案外ラクにできたので…その手順を簡単に説明する事で、Microsoft Docs を直す人が増えるとｲｲﾅｰという趣旨の記事です。
はじめに
Microsoft Docs へのContribution についてのドキュメントは
https://docs.microsoft.com/ja-jp/contribute/
に完備されています。判らない事は全部こちらに載っているはずです。ただ完全過ぎて全部読むのも大変なので、適度に端折っているのが今回の記事になります。
- 最初に、GitHub のアカウントが必要です。
- やり取りは英語になります。
※この記事、以降GitHub に慣れている人には今更な話が多いです。
Microsoft Docs の文書を表示する
この1年程で、これまでMSDN Documents として整備されていた文書の大部分は新サイト Microsoft Docs に移行しています。
 |
| Microsoft Docs トップページ |
コンテンツ自体はMarkdown（のGitHub拡張）で記述されており、GitHubで管理されています。そして、一部の文書についてはユーザーがPull Request（以降PR、変更要求）を送ることが可能になっています。
そういった文書は、画面の右カラムに「Edit」ボタンがついています。文書によっては右カラムでは無く、真ん中のコンテンツエリアのセクション毎に「Edit」ボタンがついている物もあります。
このEdit ボタンをクリックすると、GitHub上の当該コンテンツのページに飛びます（ボタンの名前に反して、この時点では表示だけで編集は始まりません。気軽にポチっていいです）。このボタンが表示されていない場合、現在の所その文書にPRを送ることはできません。後で触れます。
 |
| Edit ボタンが右カラムに表示されている例 ちなみにウィンドウをもう少し狭くすると左上に移動します Acrylic material |
 |
| セクション毎にEdit ボタンが表示される例 Windows.ApplicationModel.Core.CoreApplication |
GitHub 上での作業
ソースの表示
Microsoft Docs 上の文書に対応する、GitHub 上のソースが表示されます。
 |
| GitHub 上の Acrylic ソース |
編集
編集を始めるには、右上の鉛筆アイコンをクリックします。
GitHubのMarkdown エディタが表示され、編集が可能になります。
画面上部に説明が出ているように、この編集作業は作業者（あなた）のリポジトリの中に作成されるブランチ（この画像の例ではMicrosoft/windows-uwp）に対して行われます。
プレビューで確認しつつポチポチ書きましょう。
 |
| Markdown エディタ タブ切り替えでプレビューを表示できます |
編集が終わったら画面の一番下までスクロールします。
Propose file change のフォームに変更のタイトルと説明を書きます。ボタンをクリックすると、Create Pull Request の画面に飛びます。
 |
| ファイル変更の提案 簡潔なタイトルと内容の説明を書きます |
Pull Request の作成
先ほど行った編集前・後の比較が表示されます。諸々確認の上で覚悟が出来たらCreate Pull Request ボタンを押して作成です。
このタイミングで、
- 自動的に自分のリポジトリ内にブランチが作成（フォーク）され、
- そこで編集が反映され、
- その差分がPull RequestとしてMicrosoft側に送信
と物事が一気に進みます。今迄は基本自分の中だけでの作業でしたが、ここでポチっとした以降は担当者に通知が飛び、他の人との共同作業になります。
なお、簡単な編集・修正では、基本的にはこのリポジトリ上での自動フォークを使ってほしいようです。普通にローカルにブランチ作って編集してSyncして…というのはまだあんまりのようです。
 |
| Pull Request作成画面 |
Pull Request の処理
以降は、処理が進む様子をPull Request のページで確認します。
基本的には、
- 共通のレビュー担当者がPRの書式等をざっくり確認し、
- 次にそのドキュメントの担当が中身を確認し、
- OKならマージされて完了！
という流れです。大体数日から１週間～１０日くらいで終わる感じです。また、マージされてから実際のMicrosoft Docs のWeb側に反映されるにはさらに数時間掛かります。
 |
| PRの処理フロー これは以前に私が上げた、Acrylicのページのカラーブラシの名前間違ってるから直したよというPRです |
編集できる文書・できない文書
上でも触れましたが、Edit ボタンが表示されていない文書にPR を送ることはできません。
2017年11月現在では、UWP App、WinRT APIについてはen-us 、英語ページはほぼ全てEdit ボタンがあり、PRを送ることができます。しかし日本語ページは全て未対応です。
これは文書のジャンルによって状況が違います。例えば .NET や Outlook では、日本語に対する修正も可能になっています。
Outlook では日本語直してキャンペーン中だそうです。
https://www.facebook.com/MVPAwardProgram.JP/posts/1476999755669677
日本語のちゃんとした説明もあります。人力翻訳には温かみがある…
https://github.com/OfficeDev/outlook-dev-docs.ja-jp/blob/live/CONTRIBUTING.md
なお、編集できる・できないについて特にまとまったディレクトリ等があるわけでは無く、その文書にEdit ボタンがあるかどうかで判断して下さい、という事のようです。
0 件のコメント:
コメントを投稿