Adapting Design Docs Practice for Mid-Sized Companies
こんにちは、Finatextの @taiki45 です。この記事はFinatextグループ10周年記念アドベントカレンダーの14日目の記事です。昨日は河端さんが「保険業界の Vertical SaaS『Inspire』のビジネスモデル」という記事を公開しています。
インターネットサービス業界でDesign Docsと呼ばれているプラクティスがあります。これは、それなりに規模のあるなにかを作ったりタスクを行う前に、解決する問題や考慮事項や取りうる選択肢やそのトレードオフなどを文書としてまとめたもの(design doc)を書くというプラクティスです。
Design Docsプラクティスは、複数のチームやある程度の多さのステークホルダーをalignするという側面もあって大企業でよく使われていると思うのですが、中規模(300人程度)の企業でもDesign Docsプラクティスを行うことで、より精度の高い意思決定を行い、プロジェクトのリスクを軽減して、ソフトウェア開発を効率的にすることができるので、その実践や気をつけていることについて紹介します。
Design Docsとは
一番有名であろうGoogleのDesign Docsのプラクティスについて説明しているこの記事があるので、(この記事ではあまり重要ではないですが)一般的なDesign Docsとはなにかについてはこれを参照してください: https://www.industrialempathy.com/posts/design-docs-at-google/
この記事ではdesign docsに書く内容として、
- 解決したい問題、モチベーション、考慮事項
- 取れる選択肢とそれぞれのpros/cons
- どの選択肢を採用するか、それはなぜか
あたりを想定しています。
Design Docsの利点
ある程度の大きさのタスクや問題解決をする際に、その意思決定の精度を効率的に高めたいというのがモチベーションです。
例えば、全体最適を度外視すると、会社全員1つの部屋に集めて自分がこれからしようとすることを説明して意見やツッコミをもらうのが、局所的には最も効率良く意思決定の精度が高くなります。しかしこのアプローチは組織の規模が大きくなるとすぐに破綻します。次善の策として、文章として問題やアプローチを言語化することで、問題領域の特定の部分(例えばセキュリティや他のチームの開発しているプラットフォームやコンポーネント)について、効率的にコミュニケーションして前提の間違いその他に気づいて、意思決定の精度を高めるというものです。
また、コミュニケーション以外の部分での利点として、思考を言語化・文章化することにより、考慮漏れや実は調査が足りてなかった事項が見つかることが多いです。
実践で気をつけていること
書く前
Design docを書くことはめちゃくちゃオーバーヘッドが大きいです。特に中規模の組織では合意形成という面での利益が少ないかあるいは無いので、大規模な組織よりさらに書くことのコスパについて慎重になる必要があります。
a. 問題及びそのアプローチがほぼ自明ではないか？
b. PR descriptionで実装後に説明するので十分ではないか？
c. Quick chatやミーティングの方が効率的ではないか？
d. 量があまり多くなくかつ議論の余地があまりない場合GitHub issueに書く方が効率的ではないか？
e. プロトタイピングを行う方が効率的ではないか？
このあたりを考慮しています。
(b)について、手戻りのコストが低い場合、事前に文章を書くコストを省いて、いきなり実装を出してコミュニケーションした方が正確性が高い意思決定ができるので常にそういう選択肢もおいています。(a)に近いですね。
(c)について、中規模の環境ではそもそもステークホルダーやコミュニケーションパスが少量なケースが多いので、直接のコミュニケーションの方が効率的なケースは多々あります。
(d)のGitHub issueとの使い分けで言うと、量が少なくissueで見やすいかつ議論の余地が少ない問題についてはissueの方が実装に近い場所に情報を置けるのでissueの方が情報を置く場所として適していると考えています。議論の余地についていうと、GitHub issueは複数人がコメントを多く投稿していくと、それぞれがどの議論なのか整理しにくいというツールの限界があるため使い分けています。
(e)について、手を動かさないとわからないことが多い問題の場合、design docsを経由せずにプロトタイピングから直接本実装に移行する方が効率的なケースです。
またdesign docを書くか書かないかの2択ではなく、例えばあるdesign docを書いてそれをベースに口頭でのコミュニケーションを行うことも有効なケースもあります。
さらにdesign docを書く場合もいきなり書き始めないことが効率的なケースも多々あるのでそこにも注意しています。例えばよくわからないことが多い場合、その状態でもdesign docを書いたとしても中身も薄くアプローチの精度も低いので書き手・読み手ともに時間を損するだけになります。そのようなケースでは、調査・ヒアリングを繰り返したり、手を動かしてある程度のものを作って、問題の周辺領域に詳しくなった後にdesign docを書き始める方がよいです。
書く際
a. コンテキストがない人は読めなくてよい
b. 後から読む人への解説書にはしない
c. レビュー前に全て詰める、レビューは何往復もしないし、レビュー後の積極的な更新もしない
(a)について、まず最もありがちなpit fallとしてドキュメントとしての体裁を整えることに労力を費やしてしまうことです。思考の言語化と議論のためのツールなので、「コンテキストがない人も読めるようにbackgroundのセクションなどを詳細に書くこと」をしないのはコスパのために重要です。
(b)について、これは一般的なプラクティスと違う点かもしれないですが、後からdesign docsを読んで有益になることを求めないようにしています。あくまでdesign docsは本格的な実装に至る前の議論フェーズでの書捨ての道具として使って、アーキテクチャや実装に関わる意思決定について全て網羅しないことで、書くことと更新するコストを低くしようとしています。もちろん、後から意思決定の一部を参照することで将来の実装の読み手の材料になることは目指してますが、意思決定の根拠の一部であることや古い情報であることは積極的に認めています。これはプロダクトやソフトウェアのサイズが大規模になりにくいという組織上の性質があるからですね。
(c)について、文書としての価値を高める労力をかけないと言い換えてもいいかもしれないです。レビューはあくまで考慮事項の確認や方向性の合意であって、文書の良し悪しについては(ほとんど)レビューしないことが重要です。もちろん、よくわかっていない事柄についてdesign docをWIPの状態で調査したことなどをまとめておいて相談しつつクリアにする、という使い方は有用ですが、よくわかっていない事柄が多すぎる場合は、design docを書く前に別の方法でコミュニケーションしたり調査を進めてからdesign docを書いて方向性の合意を取る方がレビューコストも下がってうまくいくと考えています。
(c)のレビュー後の更新については、(b)と関連していて議論が終わってしまえば基本的にそのdesign docは不要くらいの考えで運用していて、実装に入った後にわかったことや方向転換について詳細に残さないことで更新するコストを下げています。もちろんコスト少なく更新できるケースでは更新した方がよいですが、大抵は出来上がった文書を更新するのは難しいので。
運用時
a. 書いて議論した結果なんか違ったねで破棄(archive)することはある
b. 承認はいらない。LGTMくらい。
(a)について、ドキュメントを書き慣れない人がドキュメントを書くことで成果物について気持ちを持つことはあると思いますが、間違った意思決定を防げたことで十分にコストは回収しているので、サンクコストを恐れないのは大事です。また、実装前の設計の精度が高い状況は少ないので設計にコストをかけすぎないために、design docsを書き直して過去のものをリンクしたり、機能ごとやフェーズ毎にスコープを分割するという手もあります。
(b)について、「design docsが承認されないと次に進めない」とはしていないです。他にいい言葉が思いつかないのでレビューという言葉を使ってますが、レビュープロセスは「なんかよさそう」くらいでもOKで運用しています。Design docsを書くフェーズでは厳密な計画や設計はできない、と考えているからで、セキュリティやコンプライアンスその他のrequiredなレビューは別のフェーズで行っています。もちろん、セキュリティその他の関心事をdesign docsの中で議論したり詰められるケースであれば、そこでやるのが良いですし、そのための道具だと考えています。
(b)について、承認フローはないのですが、合意形成のツールとして使う場面もあります。ですが、これくらいのサイズの組織ではあまりそれに囚われずに「やればできる」の精神で進めることも大事なので重要視をしていないです。
テンプレート
Design docsを議論を行う道具として使う性質上、文章を指定しつつコメントすることが効率的にできるツールが望ましいのでFinatextではGoogle Docsを利用しています。Google Docsにはテンプレート機能があるのでそれを用意して新規にdesign docsを書くときのレールにしています。
タイトルとメタ情報
タイトルの下に以下のメタ情報欄を用意しています。
- Owner: この議論をドライブする人
- Contributors: 他にいれば
- Team: チームもしくはプロジェクト
- Short self link: TODO
- Status: WIP | In-Review | Reviewed | Implemented
- Created: 1/1/2024
- Updated: 1/1/2024
- Reviewers: レビューアーまたは読んで合意したい人
オーナーやチーム情報は後になって聞きたい時に履歴を見ずに誰やどのチームに聞くといいのかわかるようにつけています。
Statusフィールドは今の状態を太字にする運用にしています。
Short self linkはGoogle DocsのURLがランダムな文字列で内容と関連性が薄く使いづらいので用意しています。Finatextではまだ社内短縮URLサービス用意してないのでしばらく “TODO” ですが…(機運を高めています)
Overview
ドキュメントが長ければ概要を書く。
と書いていて省略可能にしています。
Background
共有しておくべき前提を書く。なければ省略。壮大になりすぎないように注意。Design Docsにおいては「コンテキストがわかる人だけが議論できればOK」という前提が重要。
というplaceholder messageを書いています。
Problems to Solve
どんな問題や改善すべき状況を解決したいのかを書く。一番重要。「どこまでを考慮するのか」のようなスコープを言語化することも重要。
Proposal
上記で言語化した解決したい問題について、解決するために「取れる選択肢とそれぞれのpros/cons」と「実際にどのアプローチを選択するか、なぜか」を書く。
また、それを実現するにあたって、
- 調査したこと・まだ調査してないこと
- 考慮すべき事項
も言語化する。図とかも使うとなおよし。
FAQ
Proposalセクションにうまく盛り込めなかったけど他の人が疑問に思ったを書くと良い。あとからうまくProposalを更新していくのは大変なので。
とplaceholder messageを書いているように、レビュープロセス等でわかった情報などをうまく本文更新できない時に使っています。
Further Work
ここでの議論のスコープ外ではあるが、当然思い浮かぶような事項について補足する。
特にプロダクト開発に近い領域だと、あれもこれもアイディアや解決したい(が、リソース的に優先度は上げられない)問題が思い浮かぶので、夢リストとして書いておくことでレビューアー・読み手の思考コストを下げようとしています。
まとめ
Finatextでは、Design Docsプラクティスを「問題と解決策を整理する・議論する」「特定の領域に詳しい人の意見をもらう」ための道具として活用しています。他の中規模な組織でも応用でき有用な気がしているのでこの記事で紹介しました。
明日は菅原さんによる「結局、投資初心者はいつ投資を始めればいいのか？～思い立った日がベストな投資タイミング～」についての記事です。お楽しみに！
最後に、Finatextではソフトウェアエンジニアに限らず様々な職種で募集しています！金融という難しい領域ながら、信頼できるメンバーとともにおもしろいアプローチでチャレンジできる環境なので、興味がある方は下のURLからなり、ぼくのメールアドレスやLinkedinやXのDMなどからコンタクトください！
