プロダクトのドキュメントにプルリクエストを送れる仕組みがすごい

これ↓なんですけど、意外と RT や Like が付いてたので、ちゃんと書きますね。

しっかしMicrosoftのドキュメントシステム良く出来てるなー。右のEditボタン押すとGitHubが開いてすぐPR送れる。あちらでマージされれば即サイトに反映される。Contiributorsに自分のアイコンが増えた♪ これはフィードバックするのに「面倒」は理由にできないですぞ。https://t.co/9KhAwhV5PP pic.twitter.com/r46zFUvkEp

— あめいぱわーにおまかせろ! (@amay077) 2018年6月12日

このツイは Microsoft の製品やサービスのドキュメントについてなんですが、

• Microsoft Docs

というポータルがありまして、同社のサービスの多くはここでドキュメント公開されている模様です。 ここで公開されているドキュメント群は、バックエンドに GitHub^gh が使われていて、ドキュメントの修正方法に GitHub のプルリクエストの仕組みがうまく統合されています。

とても素晴らしいのは、ドキュメントの修正が 「誰でも」、 「簡単に（すなわち今すぐに）」 できることです。Microsoft アカウントは必要ありません、GitHub アカウントがあればOKです。

ドキュメントの修正を送る手順

例えば、テキトー に Visual Studio -> Visual Studio App Center とクリックしていって https://docs.microsoft.com/en-us/appcenter/dashboard/ を開いてみると、普通にドキュメントが見られるわけですが、ここでなにか誤字を見つけたとします。

そしたらすぐに、画面の右側にある「Edit」ボタンを押します。

するとなぜだか GitHub の当該ドキュメントのページが開くので、ここでも編集を示すアイコンをクリックします。

そしたら Markdown の編集画面になるので、みつけた誤字を修正します。 ここでは仮に 「EMail を E-Mail に直す」 という超どうでもいい修正をしました。

仮なので実際にはこんなPRは送らないですよ

「Propose file changes」 を押します。大丈夫です、まだ何も起こりません。

次に修正箇所の確認画面になります。

修正が問題ないことを確認したら、「Create pull request」を押します。まだ何も起こりません。

すると、次のような画面になります。

"Leave a comment" に簡単に「どんな修正をしたか」とか「なぜこの修正をしたか」などを書いて「Create pull request」 を押すと、 実際に修正が送信されます。

プルリクエストが送信されると、Microsoft のチームの人がそれをレビューし、問題なければマージされ、サイトに反映されます。

私が送った修正のプルリクエスト

App Center で Android アプリをビルドするときに、環境変数を注入する方法が間違っているのに気づいて、それを修正しました。

https://github.com/MicrosoftDocs/appcenter-docs/pull/168

「Java なんだから string じゃなくて大文字の String だろ」 とか 「文字列は \" で囲まなきゃダメだろ」 というところを直して、簡単に説明して送信しました。

送信後、こんな↓感じで、アチラのメンバーの人がリアクションしてくれました。

コメントがもらえたらすかさず :thumbsup: して、「見てますよ〜」 感を出していくと、アチラも悪い気はしないと思います。

最終的には５日後くらいにこの修正がマージされて、サイトに公開されました。

現在、該当ページは次のように修正済みです。

ついでにページ上部の contributors にアイコンが付きました、やったね。

今すぐコントリビュート！

https://docs.microsoft.com/ はローカライズもされているのですが、「とりあえず機械翻訳で出したよ」的なものも多く見られます。

例えば Xamarin Android の日本語のページのひとつ を見てみましょう。

おお、Material Theme を「材料テーマ」ときましたかｗ まあ機械翻訳だし仕方なし。 カーソルを当てると英語の原文が見られるのも便利ですごい。 ここから適切な日本語文に修正してプルリクエストを送ることができます。

日本語訳は結構難しくて、ドキュメント全体で訳の一貫性を保たせなければならない、とかあるんでしょうけど、なにかアクションを起こさないとこちらの(この日本語版ドキュメントが欲しいという)ニーズも伝わらないので、カジュアルにプルリクしてよいと思います。ダメなら Reject されるだけです。

おわりに

と、このように誰でもすぐにドキュメント修正が行える仕組み、よくできてるなあ、と感動しました^hb。 やりたい／やってほしい事が抵抗なくできるシステム、理想的なんじゃあないでしょうか。

Microsoft さんにはこの仕組み自体を我々にも使わせて欲しい！（もう公開されてるなら教えてください） 自社の製品やサービスのマニュアルもこれ使いたい！ APIリファレンスもこれで書きたい！ もはや CMS これでいいじゃん。 よろしくご検討ください。

他の事例(随時追記 ※コメントなどで募集してます)

Elasticsearch

Elasticsearch のドキュメントも、同じ仕組みであるとの情報をいただきました。

https://t.co/qppqavNAks

すっごい薄いですが「edit」というボタンがあります。ちょっと薄すぎて目を凝らさないと見えないですが…ｗ

— FUJI Goro (@__gfx__) 2018年6月13日

MDN(Mozilla Developer Network)

MDN のドキュメントも、同じ仕組みであるとの情報がありました

MDNも忘れないで！MDNは2006年以前からその仕組みがある。MSのこの改善は素晴らしい。もっと早くに欲しかった。 / “プロダクトのドキュメントにプルリクエストを送れる仕組みがすごい” https://t.co/G1jeSeIKcJ

— test (@in_dow) 2018年6月13日

• HTMLを始めよう - ウェブ開発を学ぶ | MDN

なるほど右上に「編集」ボタンがあります。

Docker

Docker ドキュメント日本語化プロジェクト — Docker-docs-ja 17.06.Beta ドキュメント は Read the Docs が使われているようです。

AWS(Amazon Web Services)

ドキュメントの言語を English にしたときのみ「Edit on Github」のボタンが現れます(コメントで教えていただきました。)。

例 - https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html

さらに（すみません、まとめて）

GitHub にホストされているものに関しては、むしろ、できないほうが驚く程度には一般的な印象です。

との意見と以下の情報をコメントにていただきました。

• Babel (右上に EDIT)
• Webpack (右上に EDIT DOCUMENT)
• ESLint (フッターに Edit this page)
• Vue.js (フッターに Edit this page)
• React (フッターの上に Edit this page)
• npm (フッターに Send a pull request!)

この機能を実現可能なサービス・ソフトウェア

Read the Docs, GitBook

Read the Docs、 GitBook というサービスもあるそうです、これらは我々がコンテンツを提供する側になれる SaaS ですね。

https://t.co/3nCVFfK0a3 とか https://t.co/Kxb2KwG0dF とか使えば気軽に実現できます。アイコンはないけど。 / “プロダクトのドキュメントにプルリクエストを送れる仕組みがすごい” https://t.co/Cq1YipcuHL

— ㈱にゃーん (@Kengo_TODA) 2018年6月13日

セルフホストできるようなプロダクトがあれば企業や団体の閉じた世界で使えそうです。