“「書く」のは特別な道具” という記事のなかで検索会社の Design Docs というやり方が すっかり過去のものになってしまったかのように読めなくもなかったため、私の理解を書いてみたい。 ただ私は検索会社メインストリームであろうクラウドヒャッホイな仕事はしていないので色々間違ってるかもしれない。 これを呼んで憤った同僚各位はぜひついったや会社の中などでこっそり教えてください。追記します。

Design Docs は考えるための仕組みというより、むしろ議論のための仕組みである、とおもう。 この二つは矛盾しない。文章にすれば考えがまとまるのは確かだし、議論自体も思考を支える道具の一つだから。 けれど文章はまず読者のために書くもの。そして一番の読者は誰かというと、チームメイトや隣接プロジェクトの同僚達だ。

誰のため？

Design Docs の意義はコードレビューと合わせて考えるとわかりやすい。 検索会社周辺ではレポジトリにコードをチェックインする上でレビューは必須とされている。 GitHub 圏の素敵カンパニー達にもそういうところは多いと伝え聞いているので、特段珍しい話ではない。

さて、これから新しいシステムを作る、大きな変更や拡張をする、そんな時のことを考えてみよう。 とりあえず適当に書きはじめたコードをレビューに出したとする。 このときレビューをする同僚は、何をもとにその善し悪しを判断すれば良いだろう。 その理解を助けるのが Design Docs の一番の価値だと思えば多分だいたい合っている。 レビュアは文書を読んで大筋を把握し、その筋を進める一歩としてレビュー対象のコードをにらむ。

プロジェクトの規模やフェーズによって、コードレビュー以外にも色々相談しておくべきことがある。 スケーラビリティ・・・というと曖昧だけれど、たとえばアプリケーションが使うストレージや API ををホストするチームに、 こんな感じで API を叩きたい/データをおきたいんだけど、キャパシティ足りますよね、などと相談する。 最近だとセキュリティやプライバシーはかなり厳しくチェックされるらしく、そのために要件をクリアにしないといけない。 そういうチェックや相談に向けた事前資料も Design Docs の範疇になる。それぞれ読者が違うから、用途にあわせて文書を用意する。 相手はその文書を呼んで、大丈夫ですとかここがダメとか、そういう話をする。 定型的なチェックについては文書にもテンプレートがある、はず。

プロジェクトが大きいほどチェックや相談を頼む相手も増える。 沢山の API をつかう、隣接するプロジェクトに変更をお願いする、 ユーザの個人情報を扱う、大量のトラフィックが見込まれている、 新しくサーバを増やす分モニタリングを頼みたい・・・どんな会社でも似たようなややこしさはあるだろうけれど、 検索の会社はでかい上に組織の境目が緩いので、依存関係の枝は広がりやすいように見える。 聞き慣れないオフィスに出張するという同僚に、「そんなところに X のチームがあるんですねえ」と聞くと 「いや今度のプロジェクトは Y のデータを使わせてもらうんで相談にいくんですよ」なんて答えが返ってくることはよくある。 私の出張先は本社のあるツクバ・カルフォルニアばかりなのでやや羨ましい。

レビューと文書

レビューの議論はメールベースで進むこともあれば、対面やビデオ会議で進むこともあろうだろう。 どちらにせよ基本はまずメールでドキュメントへのリンクを送っておいて、必要に応じて密な対話に入るのが定石のようす。 いきなり口頭で説明されてもお互い時間の無駄だし、ミーティングのために朝早く起きたり相手のとこまで出張したりするのもしんどいしね・・・。