Design Docsのいけすかなさから始まる一連の記事を読んで、やっぱりみんなDesign docで苦労しているんだなぁと思った。自分も仕事でDesign docを書いたり他の人が書いたものをレビューしたりするけど、文書を書いたり読んだりする面倒くささの割に得られるものが想像し辛かったり、読んでも結局何が言いたいのか分からなかったりして、本当に意味があるのかどうか疑問に思うことが多かった。
Design docに関する自分の肌感覚はjmukさんの返信で言及されているものがかなり近い。抽象度の高いところほど後戻りし辛かったり、すれ違いが起きた時の手戻りが大きかったりして間違いが起きた時のダメージが大きいので、そういった箇所での認識をすり合わせできたり、自分の認識が甘かったところにツッコミを入れてもらえたりするとDesign docを書いた意味があったなと思う。逆に、細かい実装の詳細に関して得るものがあることはあまりない。記事中でも言及されているようにそもそもDesign docからコードが乖離することはよくあるし、karino2さんの返信でも指摘されているようにコードを書くこととデザインすることは密接に関連し合っているので、ウォーターフォール的にデザイン先行でドキュメントを書くという行為があまり現実的でないという面もある。そういった点をひっくるめて、Design docの価値としては
けっきょくのところ要は、変更1個でおわるようなものじゃないなら、いきなりコードを送りつけるんじゃなくて何をしたいのか、どういうことを考えてやったことなのか教えてくれ、という話なんではないか。また、数あるアプローチのうちなぜこのアプローチを採用したか自明でないなら、その理由が知りたくもなる。issueでもいいんだけど、issueはそこまで長々といろいろ検討したりする場でもないし。
という説明がかなり的を得ているように感じている。
Design docの具体的な構成要素で言うと、shinhさんの返信でも触れられているように、BackgroundとMotivationはかなり有用性が高いと思う。一人でやる趣味のプログラミングならともかく、仕事では大抵チームでコードを共有する必要があるし、好き勝手な問題を解けばいい訳でもない。自分の現状認識が正しいのか、問題の定義が正しいのか、その問題に解く価値があるのかなど、問題に取り掛かる前に答えを出しておくべき質問はたくさんある。大抵の場合はこのような質問に対して自分一人で確信度の高い答えを出すことは難しいので、文書の形にして他の人に問うということには大きな意義がある。
仮になんらかの理由で自分自身で確信を得ていたとしても、プロジェクトの最後には成果物はチーム全体でメンテナンスする共有物になるため、なぜこの問題を解き、なぜチームでコストを払ってまでメンテナンスする価値があるかの理由を広く共有する必要がある。特に個人的な経験としては、自分が必要性を確信していたとしても、問題意識がチームメンバーやマネージャーと共有されていないというケースは結構あるので、コミュニケーションを円滑にする意味でもDesign docを書く意味はあると思う。この場合は必ずしもDesign docの形を取る必要はないけど、既にそういうフレームワークがあるのにあえて避ける理由も特にない。
BackgroundとMotivationよりも具体的な要素に関しては、影響範囲が特に大きいもの以外はほとんど無視しても良いと思っている。取り上げる価値があるものとしては、例えば
- 問題への大まかなアプローチ（文章で数段落、疑似コードで数十行くらい）
- 外部に公開するAPIの設計
- セキュリティやプライバシー関係のハンドリング
- Roll outの計画
などが考えられる。逆に、これより具体的な実装の詳細や使用するライブラリの選定などに関しては、先に述べたような理由によりデザイン先行にする意味があまりないので、極端に言えば省略してしまっても良いと思っている。
個人的には、半年くらい前まではDesign docに何を書けばいいのか今ひとつ分かっていなかったけど、最近になってこれらの事実に気が付いたので、BackgroundとMotivationの説明に時間をかけるようにして、他の部分は適当に済ませるような方針にしている。ただ、こうするとやはりコード部分の詰めが甘くなって実装が二転三転してしまうといった問題も感じているので、Design docと同時か直後くらいに（実働）1日くらいで小さいPoCを作ってコードレビューのようなものを開くといいのかなぁとも思っている。