■ 1. Design Docに表れるエンジニアの能力
- Design Docに表れるもの:
- 設計時にどこまで選択肢を広げ、リスクを深掘りし、何を今決めるべきか判断できているか
- 優秀なエンジニアであれば押さえて欲しいポイントが存在する
- Design Docだけで決まらない能力:
- Design Docだけでエンジニアの能力が決まるわけではない
- フォーマット非依存:
- Design Docのフォーマットは組織によって異なるため、特定のフォーマットに依存しない形で論じる
■ 2. Design Docの目的
- 不確実性の可視化と排除:
- Design Docは開発に入る前に不確実性を可視化し、可能な限り排除するためのもの
- 実装開始後に想定外が発覚するより、事前にドキュメントで詰めた方が手戻りが少ない
- 本記事の焦点:
- エンジニア同士の認識合わせや記録を残す観点もあるが、不確実性の可視化と排除にフォーカスする
- 完璧な設計は不要:
- 開発対象によっては事前に完璧な設計を描くこと自体が難しい
- どの程度の不確実性を可視化し排除するかは開発対象に依存する
■ 3. レビューで注視する3項目
- 注視する3項目:
- 代替案、懸念点、未決定事項の3つ
- フォーマット上セクションとして明示されない場合もあるが、相当する記載を注意して読む
- 大前提となる条件:
- 設計したシステムアーキテクチャやテーブル設計が適切な形になっていることが大前提
- その上でどこをレビューするのかという話になる
■ 4. 代替案
- 代替案の定義:
- 今回採用しなかった選択肢
- トレードオフの選択:
- エンジニアリングに絶対的な正解はなく、意思決定はトレードオフを選択した結果になる
- どういった選択肢があり、どういった理由で今回の選択をしたのかがレビュアーとして最も気になる
- 優秀なエンジニアの特徴:
- 代替案の数やトレードオフの言語化が適切
- A案、B案、C案を挙げ、Cは却下、AとBを比較するというふうに選択肢と判断基準がクリアに書ける
- 代替案が出てこない場合:
- そもそも他の選択肢を考えたのかという疑念を持たれる
■ 5. 懸念点
- 懸念点の位置づけ:
- 書き手の懸念が言語化されている場所であり、レビュアーが最も慎重にレビューすべき内容
- 記載内容は大きく2種類に分かれる
- 不安が残るもの:
- トレードオフを考慮して意思決定しても不安が残ることはある
- その不安が無視できない程度のものであれば明示的に記載する
- 代替案との違い:
- 代替案は選ばなかった選択肢であり、その意思決定に懸念や不安がない状態の内容
- 懸念点はA案を選択した前提で書きつつ、その点は不安が残るというものを記載する
- 分からないから助けてほしいもの:
- 考えたが全然分からないものはそのまま書いておく
- 書いておけばレビュアーが助けてくれる
■ 6. 未決定事項
- 未決定事項の対象:
- 実装時に考えればいいもの、そもそも考慮しなくていいもの、考慮できないもの
- 明記すべき内容:
- なぜ今は決めないのか
- いつ誰が決めるのか
- あえて決めない利点:
- 実装に入るまでのリードタイムを短縮できる
- 実装時に決めることが明確になり、タスク漏れが発生しづらくなる
- Design Doc承認後にチケット化すればよい
■ 7. 3項目が示す能力
- 代替案が示すもの:
- エンジニアとしての引き出しの多さ
- 懸念点が示すもの:
- エンジニアとしての思考の深さ
- 未決定事項が示すもの:
- 不確実性を左右するポイントを見極める嗅覚
- 記載量は基準にならない:
- 記載量が多ければいい、少なければいいという話ではない
- 開発対象によって何をどう言語化すべきかが変わる
■ 8. ToB SaaSでの具体例
- スケールの考慮:
- ToB SaaSではデータ量やリクエスト量の増加を考慮する必要がある
- 今回作る機能は何年持つのかを考えておきたい
- 逆算による判断:
- 1年後、3年後の事業成長から顧客数やテーブルのレコード数を逆算する
- 1年もたせるにはこれは不要、3年持たせるにはこれが必要という判断をする
- 代替案での言語化:
- 優秀なエンジニアほどこうした観点を代替案のセクションで上手く言語化し、適切に意思決定する
- 懸念点での言語化:
- 1年持つ想定でも、こうなった場合は1年持たないという想定外のトラブルは起こりうる
- そうしたケースは懸念点のセクションに記載する
■ 9. 等級要件との対応
- 中長期的な視点との関係:
- 上位のレベル・等級の要件には中長期的な視点で設計・開発できることが含まれる
- 代替案、懸念点、未決定事項はそうした中長期的な観点を問うものであり、優秀なエンジニアほど上手く書ける
■ 10. ドキュメンテーション能力
- ドキュメントの威力:
- ドキュメントは自分の考えを他人に共有する際にとても便利なツール
- 共有する情報量が多いほど、共有する相手が多いほど威力を発揮する
- 上位職に必須のスキル:
- スタッフエンジニアやプリンシパルエンジニアには品質の高いドキュメントを書けるスキルが必須
- ドキュメントを書くことを嫌がらないマインドも重要
- 書けない場合の帰結:
- 自分の考えを組織に共有できず、組織を動かすような大きな仕事ができない