GitHub
Markdown
CMS

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

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

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

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

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

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

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

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

image.png

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

image.png

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

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

image.png

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

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

image.png

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

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

image.png

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

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

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

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

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

image.png

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

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

image.png

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

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

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

image.png

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

image.png

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

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

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

image.png

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

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

おわりに

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

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

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

Elasticsearch

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

MDN(Mozilla Developer Network)

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 DocsGitBook というサービスもあるそうです、これらは我々がコンテンツを提供する側になれる SaaS ですね。

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


  1. ちなみにこの仕組みは GitHub 買収発表以前からあったものです、念の為。 

  2. Android や iOS のドキュメントもこんな風にすぐフィードバックできるようになって欲しい!