Design docs というのが昔からあまり好きでない。読むのも書くのも好きでない。 仕事で文書を書くのはやぶさかではないけど Design docs はなんとなくいや。 せっかくなのでこのイヤさを言語化してみたい。
Design Docs とはなにか
自分が想定している Design docs は この文章が説明しているようなものだ。 なにかそれなりの規模があるものを作る時に設計やそのトレードオフをざっと文書化する文書。 もっというと一般名詞の design docs ではなく、リンク先に書いてあるような自分の勤務先固有の The Design Docs 文化が好きでない。
「設計やそのトレードオフをざっと文書化する。」 それだけ聞くと割と良いもののような気がして、自分もある時期までは良いものだと思っていた。 「ドキュメンテーション」というのは、プログラミングのポップカルチャーにおいては伝統的に嫌われものである。 そんななか Design docs は旧来のドキュメンテーションが持つ官僚的、形式的なイメージを覆し、 必要最低限の情報をインフォーマルに伝える手段として新風を吹き込んだ・・・気がしていた。十年以上前、具体的な実装を見るまでは。
しかし実際に仕事で Design docs を読んだり書いたりしてみると色々と欠点も見えてくる。
欠点 1: 想定されている問題領域の狭さ
Design docs は、ある規模のものを「新規に」開発する暗の想定がある。 ついでにそこで想定されているのはサーバサイドのシステムみたいなやつである。 社内に用意されているテンプレートはこうした想定を強く織り込んでいる。 けれどモバイルアプリのコードをリファクタリングをしたり UI を増改築したり性能改善をしたり奇妙なバグを直したりに 大半の時間を費やしているしている自分にとって、この想定は他人事。
先にリンクした文書では、インクリメンタルで比較的規模の小さい仕事には “mini design doc” を書くと良いといってるけど、 その書き方については特に論じず、簡潔にしとけよ、オーバーヘッドでかいだろ、とかいうだけ。この無関心さが暗黙の想定を裏付けている。 実際、あたらしいシステムをバンバン設計なさっている立派な皆様ほど Design docs を好まれる。
欠点 2: 期待されている守備範囲の広さ
Design docs の主目的はなにか大きなものをつくる前に重要な意思決定 (アーキテクチャといってもよい) をレビューすることである。 つまりレビューが済んだら基本的には用済みだ。にも関わらず、 Design docs は部外者や新参者が既存のソフトウェアのデザインを読み解くための文書としても使われている。 「古くなってるけどだいたい合ってるよね」という感じで読まれる想定がある。
この想定は Design docs を冗長にするし、焦点を滲ませる。 レビューをするであろうチームメイト相手なら共有しているコンテクストを頼りに「全体像はだいたいいつものかんじ」と省略して本題に入り 議論すべき論点を絞れるはずなのに、読み手が知っている話をダラダラと書きがち。 ミーティングでレビューされた日には眠くなってしまう。
欠点 3: 不確実性の軽視
Design docs は、暗にデザインの確度の高さを期待している。つまり「これでできるはず」という態度をとりがちである。 先にリンクした文書では, エンジニアリングの問題なんて多くは “set of known problem” でしょと書いているけれど、 そうはいっても相対的と未知/不安な要素はあるはず。だからこそレビューしてもらうんじゃないの？
それらの不安要素こそレビューを通じて議論したいポイントのはずなのだから強調されてしかるべきだが、 そういう率直さを感じられる Design docs を見かけることは少ない。 しいていえば問題のスコープや non-goal 語る際に風呂敷を小さめにすることで目配せを送るくらい。
実際に巨大なコミットメントが発生し権力者の approval が必要な重要プロジェクトの初期デザインとかは 現実問題としてある程度の確度は必要だろうし調査や試作にも時間をかけるだろう。 Design doc も自信作ができるまで iterate すればよい。 が、それを日常に持ち込まないでほしい。テンプレに draft/ready-to-review/approved とか入れないでくれ。 書かれる文書の 90% は最後まで draft じゃん。
過剰な期待と後光
こうした Design docs の残念さは、現実には Design docs でないテキストの不在として理解する方が腑に落ちる気がする。 Design docs が生まれた 15-20 年くらい前というのは agile movement が台頭しはじめた頃で、 世の中ではまだ巨大な「仕様書」が幅を利かせていた。
当時まだわりかしスタートアップだったであろう Google にはそういう官僚的ソフトウェア開発への反骨精神があり、 一方で事前の設計や議論の必要性もあり、最低限必要このくらいはやろうね、と生まれたのが Design docs … なんじゃないかな。 ついでにいうと開発されているソフトウェアも既存コードベースの拡張より新しいものをバンバンつくるフェーズだったに違いない。
月日は流れ、会社はでかくなり、コードもでかくなり、コードベースの寿命も伸びた。 同時に世の中はインターネット・ソフトウェアの開発に伴う様々な性質、たとえば連続的で、漸近的で、実験的で、運用と一体化していること、への理解を深めた。 ソフトウェア開発の流儀もかわり、沢山のイノベーションがあって、 ソフトウェア・エンジニアリングはプログラミングの時間積分になった。
Design docs はそうした進歩を織り込めていない。
別に Design docs 自体が進歩を織り込まなくてもいんだけど、その周辺にもあまり進歩がない…というのはちょっと言いすぎて、 たとえば Software Engineering at Google という本では “Design Docs” の他に “Reference Documentation”, “Tutorials”, “Conceptual Documentation”, “Landing Pages” といった種別を議論している。世の中でもそうした議論は沢山あることだろう。 けれどこういう最近のドキュメンテーションに関する議論は Design docs が一部の人に対して持っているマインドシェア/後光を上書きできていない。 キャッチーさが足りない。
足りていないもの
そんなわけで誰か Design docs をやっつける、というか肩の荷をおろしてあげる、 キャッチーでモダーンなドキュメンテーションのやり方を考えてくれないかなあとぼんやり思いつつ早幾年。
まず「ドキュメンテーション」というのは若干 stigmatized に思えるので「テキスト」とでも呼んでおこう。 モダンなソフトウェア開発にテキストはどうあるべきか。大きな軸は二つあると思う。
まず議論、意思決定のためのテキストと解説のためのテキストを分離。Design docs はこれを混同して簡潔さを欠きがちだと先に書いた。 モダンテキストはそういう問題を乗り越えていってほしい。
そして小規模化と高頻度化。長いのよくない。ソフトウェア開発はインクリメンタルになったんだから、テキストもそれを織り込んでほしい。 かわりにもうちょっと頻繁に書いてほしい。というかメールとかバグトラッカーのコメントとかコードレビューのスレッドとかに書いている ランダムなテキスト、もうちょっと名前と構造と発見可能性を与えてくれ！もう Gmail の検索で探すとか嫌なんだ！！
目についたよさげな事例たち
実際のところモダンテキストの試みはそれなりにある。
特にオープンソース・コミュニティの成熟化にともない「解説」の方は割と充実してきている。 ぱっと良い資料がみつからないけれど、たとえばこの The Diátaxis Documentation System によれば Tutorials, HOW-TO Guides, Explanation, Reference という軸があるとしている。なるほど。
最近だと ARCHITECTURE.md というのを書くと良いよ という話があって、これもなるほどなと思う。
勢い余って悪口を書いてしまった Google にも良いアイデアはあって、たとえば Codelabs。 要するにチュートリアルなんだけど、ステップバイステップで手を動かすのに特化したフォーマットを持つ。 (Android の例) こうやってフォーマットが構造化されていると書く方も迷いがないし、読む側の期待値もはっきりする。
もうひとつは “Life of X” というフォーマットのレクチャー。 目的は先の ARCHITECTURE.md に似ていて、プロジェクトの新入りがソフトウェアの概要を理解するために用意される。 一番よく知られているのは “Life of A Query” というやつで、ウェブ検索でワードを入力すると そのクエリがどんなサーバに飛んでいってどこをどうたらい回された果てに結果が返ってくるのか、ロードバランサからフロントエンド、 バックエンドまで含めウォークスルーする。視点を動かしながらデザインを描き出すところがよい。
今はどうだか知らないけどその昔 Life of A Query は新入社員研修のヒトコマで、説明のわかりやすさとシステムの複雑さの両方に関心したのを覚えている。 “Life of X” は Codelabs よりハイレベルで書き手/話し手に求められるクリエイティビティも高い。 そのため残念ながら数はそれほど多くない。でもでかいチームには用意されている傾向。 たとえば: Youtube が使っていた(まだ使ってるのかな?) MySQL クラスタマネージャ Vittes の Life of A Query, Chrome の Life of A Pixel (ビデオ).
あまり目につかないもの
一方で議論と意思決定のためのテキストは、仕事での必要性は高いわりに自分はあまり良いスタイルを見つけられていない。 風のうわさに伝え聞く Amazon の narrative/6-pager というやつがよさそうだが、外からは実体がよくわからない。 だから中の人が書いたブログなどを(こういうのとかこういうのとか)目を皿のようにして読んじゃう。 （最近でたインサイダー本も聴き始めました。)
Design docs を倒す・・・じゃなくて弱体化するにはこの議論のためのテキストに発明が必要だと思うんだけど、 なんかいいのないですかねえ。どうですか皆様。