GitHub のコードブラウザはディレクトリのページでまず README を表示してくれる。これは小さいながらすごく良い発明だったと思う。今では GitHub に限らずソースコードをホストするサイトは概ねこの仕様に従っている。

あるディレクトリやパッケージになにがあるかを説明したいことは多い。Javadoc にもそういう機能があった。でも言語を問わず README を書ける方が堅牢でいい。言語固有の拡張はあっていいと思うけれど。

会社の中にあるコードブラウザも数年前から README 表示がついた。Monorepo を採用していると README はプロジェクトのホームページみたいになる 。GitHub でいうとルートディレクトリの README が重要なのと同じ。これがない時代はいったいどうしてたのかと不思議になるくらいの必須機能。

ディレクトリ単位で README をつけられる機能、ソースコードの文脈以外でも欲しいことがよくある。ちょっと前から Google Apps に Team Drive という機能がようやく追加され、チームのドキュメントはここに集約しましょうという話になる。けれどディレクトリにファイルが並んでるだけだと、そこに本来なにがあるべきといった情報が足らず膨大なドキュメント群を navigate できない。

ここでディレクトリ単位の REDME があったらどれだけ便利だろう。とりあえず新入りはこのドキュメントを読め、新しい design doc はここにおけ、ミーティングの議事録はここ。そんなガイドを書いておける。今はそういう情報は Google Sites （まだあるよ！）に書くことが多いのだけれど, コードに近いドキュメントは markdown でレポジトリに入れそうでない文書は Docs で書く結果 Sites に残された情報って README 代替以外でそんなにないのだよね。しかも Sites と Docs は認知的に遠い上に主戦場が Docs なせいで README ページは保守されそこねがち。Docs に README があればもうチーム内情報の整理に Sites いらないじゃん。

ドキュメントはぜんぶ Markdown で書けば Docs だっていらないじゃん、という主張はありうるし、実際そういうチームもある。ただレビューしたり図を書いたりするのは Docs の方がだいぶラク。Docs がコードのレポジトリにチェックインできたらなあ・・・と思う瞬間がないではない。それは MS Word という。別に Word を使いたいわけじゃないんだよ。

Docs に README のインライン表示がついたら、自分の中にかすかに残る Wiki への郷愁を完全に殺すことができるのになー。