優秀なエンジニアが書くDesign Docは何が違うのか?

株式会社カミナシで VPoE を務めている pospome です。 (´・ω・`)

自分はここ数年いろんなエンジニアが書いたDesign Docをレビューする機会があるんですけど、その中で「優秀なエンジニアであれば、ここは押さえて欲しい」「ここでエンジニアとしてのスキルが分かる」というポイントがありまして、今回はそれを言語化してみようと思います（同じ話を社内でしたので、せっかくなら記事にしようかなと・・・）。 もちろん、Design Docだけでエンジニアの能力が決まるわけではありません。ただ、設計時にどこまで選択肢を広げ、リスクを深掘りし、何を今決めるべきか判断できているかは、Design Docによく表れます。

Design Docのフォーマットは組織によっていろいろあると思いますが、本記事は特定のフォーマットに依存しない形で書いています。

Design Docはなぜ重要なのか?

まず前提として、Design Docがなぜ重要なのかを軽く整理しておきましょう。

Design Docは、開発に入る前に不確実性を可視化 & 可能な限り排除するためのものだと自分は捉えています。実装を始めてから「あれ、ここどうするんだっけ?」「これは想定していなかった」となるより、事前にドキュメントで詰めておいた方が手戻りが少なくて済むわけですね（"エンジニア同士で認識を合わせるため", "記録を残すため" などの観点もありますが、本記事では "不確実性を可視化 & 排除する" という点にフォーカスしています）。

とはいえ、必ずしも完璧なソリューションを描く必要はないと思っています。というか、開発対象によっては、そもそも「事前に完璧な設計を描く」ということ自体が難しかったりします。どの程度の不確実性を可視化 & 排除するのかは、開発対象に依存する話です。

Design Doc のどこを注意してレビューするか?

自分がDesign Docをレビューするときに特に注意して読むのが、以下の3つです。 これらはDesign Docのフォーマットにセクションとして明示されていることもありますが、そうでない場合もあると思います。いずれにせよ、これに相当する記載を注意して読むということです（書き手であれば、これらをしっかり書いて欲しい）。

  1. 代替案
  2. 懸念点
  3. 未決定事項

当然ながら、Design Docで設計したシステムアーキテクチャやテーブル設計が適切な形になっているというのは大前提です。 "その上でどこをレビューするのか?" という話になります。

順番に見ていきましょう。

代替案

代替案は、"今回採用しなかった選択肢" のことです。

エンジニアリングに絶対的な正解はないので、意思決定というのはトレードオフを選択した結果になります。じゃあ、どういった選択肢があって、どういった理由で今回の選択をしたのか? ここはレビュアーとしてめちゃくちゃ気になるところなんですよね。

自分の経験上、優秀なエンジニアほど代替案の数やトレードオフの言語化が適切だったりします。「A案、B案、C案がありました。Cは○○の理由で却下、AとBだと〜」というふうに、選択肢と判断基準がクリアに書けているんですよね。逆に代替案が全然出てこないDesign Docだと「そもそも他の選択肢を考えたのかな?」と思ってしまったりします。

懸念点

懸念点は、書き手の懸念が言語化されている場所なので、レビュアーとしては最も慎重にレビューすべき内容です。 懸念点に書くことは、大きく2種類あるかなと思っています。

1つ目は "不安が残るもの" です。エンジニアリングに絶対的な正解はないので、トレードオフを考慮した上で意思決定したとしても、不安が残ることはあるんですよね。もし、その不安が無視できない程度のものであれば、明示的に記載した方が良いです。代替案と似ていると思うかもしれませんが、代替案はあくまで "選ばなかった選択肢" なので、その意思決定に懸念や不安がない状態の内容になります。一方で、懸念点は「ドキュメント上はA案を選択して、それ前提で書いているけど、この点はちょっと不安なんだよなー」というものを記載します。

もう1つは "分からないから助けてほしいもの" です。Design Docの作成者が「考えてみたけど、これは全然分からん」というものもあるかもしれない。それはそのまま書いておいた方がいいです。書いておけばレビュアーが助けてくれるはずです。

未決定事項

Design Docを書く時点で考慮しなくていいもの(実装時に考えればいいものや、そもそも考慮しなくていいもの、考慮できないもの)もあると思います。そういったものは「なぜ今は決めないのか」と「いつ誰が決めるのか」を明確にしておくと良いと思います。 あえて決めないことで実装に入るまでのリードタイムを短縮できますし、実装時に決めることが明確になるので、タスク漏れも発生しづらくなります(Design Docが承認されたあとにチケット化すればいい)。

優秀なエンジニアは代替案、懸念点、未決定事項を書くのが上手い

本記事のタイトルは "優秀なエンジニアが書くDesign Docは何が違うのか?" ですが、 Design Docで設計したシステムアーキテクチャやテーブル設計が適切な形になっている上で、 優秀なエンジニアは "代替案", "懸念点", "未決定事項"を書くのが上手いです。

  • 代替案は、エンジニアとしての引き出しの多さが分かります。
  • 懸念点は、エンジニアとしての思考の深さが分かります。
  • 未決定事項は、エンジニアとして不確実性を左右するポイントを見極める嗅覚が分かります。

これらは記載量が多ければいいとか、少なければいいとかではないんですよね。開発対象によって、何をどう言語化すべきかが変わります。

具体例で考えてみましょう。例えばToB SaaSの場合、システムのスケール(データ量やリクエスト量の増加)を考慮する必要があります。もう少し具体的に言うと「今回作る機能は何年持つのか?」を考えておきたいところです。

そうなると、1年後、3年後などの事業の成長から顧客数やテーブルのレコード数を逆算し、「1年もたせるにはこれは不要」「3年持たせるにはこれが必要」という判断をしなければいけません。優秀なエンジニアほど、こういった観点を代替案のセクションで上手く言語化し、適切な意思決定をすることができるわけですね。 また、1年持つ想定だったとしても「こうなった場合は1年持たない」という想定外のトラブルが発生することもあるでしょう。そういうケースは、懸念点のセクションに記載しておくといいです。

上記は簡単な例ですが、こんなふうに代替案・懸念点・未決定事項をどう言語化するかで、エンジニアとしての引き出しの多さや思考の深さが見えてくる・・・というのが、自分がDesign Docをレビューしていて感じることだったりします。

みなさんが所属している企業にはエンジニア（従業員）のレベルや等級という概念があると思います。 上位のレベル・等級になると、要件として "中長期的な視点で設計・開発できること" みたいなものが含まれているのではないでしょうか。 今回の "代替案", "懸念点", "未決定事項" というのは、そういった中長期的な観点を問われるものなので、優秀なエンジニアほど上手く書くことができるのかなーと思っていたりします。

ドキュメンテーション能力はとても重要

ドキュメントは自分の考えを他人に共有する際にとても便利なツールです。 共有する情報量が多ければ多いほど、共有する相手が多ければ多いほど、ドキュメントは威力を発揮します。 エンジニアのレベル感として、スタッフエンジニアやプリンシパルエンジニアになると、品質の高いドキュメントを書けるスキルは必須でしょう（ドキュメントを書くことを嫌がらないマインドも重要）。 じゃないと、自分の考えを組織に共有することができないですからね。 組織を動かすような大きな仕事ができないということになってしまいます。

まとめ

今回は優秀なエンジニアのDesign Docについて書きました。 あくまで個人的に思っていることですが、少しでも参考になれば嬉しいです。

宣伝

株式会社カミナシでは以下のポジションをすごく募集しています。 興味のある方は応募してみてください。