DesignDocを導入しました

yamaguchi naoto

Published in

Eureka Engineering

7 min readDec 23, 2023

この記事は「Eureka Advent Calendar 2023」23日目の記事です。

こんにちは、Product Back-end Teamの @nao99999 です。普段はGo言語でPairsの開発をしています。

今年はチームにDesignDocを導入した話をします。

1. DesignDocとは

DesignDocとは、ソフトウェア設計を定義するための設計ドキュメントです。実際に開発をする前に、設計の背景・意図・妥当性などを記載し、それをレビューすることで、最終的なアウトプットの質を上げることを目的としています。

Eureka Back-end TeamのDesignDocは、最後の章にまとめた記事を参考にフォーマットを作成し運用しています。他社が定義するようなDesignDocとなっているかはわかりませんが、自分達なりの形で運用しています。

会社によってはRFC (Requests For Comment) と言ったりするようです。

2. 背景と課題

もともと設計ドキュメントが全く書かれていなかったわけではないのですが、下記の課題がありました。

設計の妥当性がわからない
ナレッジシェアが出来ていない
ドキュメントのレビューを強制してるわけはない
各々がフリーフォーマットで書いている
ドキュメントの場所もバラバラ

これらの課題を解決するため、チームでDesignDocの導入を決定しました。

特に「チームとしての集合知を伸ばし、ラーニングの文化を築き、最終的に各々の設計の精度を上げる」という効果を狙いました。PJも平行して多く走ってるので、チームとしてレバレッジが効いた状態にしていきたいと思いました。

3. 採用したフォーマット

後述のフォーマットを雛形にしてボタンひとつで生成するようにしています。

フォーマットは下記です。実際は社内wikiで管理されてますが、ここでは便宜上Markdownで表現します。

項目はすべて必須ではなく必要な箇所だけ書けばよいことにしています。各項目にどういったことを書くかもここに記載します。

# Background
プロジェクトの背景やPRDの抜粋を記載します。
PRDはプロダクトマネージャーが記載する、Product Requirements Documentのことです。

# Endpoint/Batch
新規で開発する or 修正対象の既存のAPIやBatchを記載します。
またOpenAPIのリンクなどをしておきます。

# Architecture Image
必要であればハイレベルなアーキテクチャ図を貼ります。

# Sequence Diagram
APIやBatchにおける詳細なシーケンス図を貼ります。主にMermaid.jsで書きます。
これによりPRのレビューがしやすくなりました。

# Data Structure

 ## ER Diagram
 ER図を貼ります。主にMermaid.jsで書きます。
 スキーマの詳細もここに含めます。

 ## Table
 開発する新規 or 既存のテーブル名

 ## Index / Access Pattern
 インデックスとアクセスパターンを記載します。
 これによりスキーマ設計とインデックス設計の妥当性を把握出来るようになりました。

# Data Life Cycle
データのライフサイクルを記載します。主にいつデータが削除されるかです。

# Cache
もしキャッシュをする場合は、キャッシュで使用するであろうリソース量を事前に見積もるための項目です。
キャッシュのサイズやヒットレートを事前に見積ることで妥当性をチェックします。

# Details
ここはフリーフォーマットです。項目に当てはまらないものはここに記載します。

# Cost
インフラコストです。

# Reference
参考リンク

フォーマットを統一することで、書き方やレビューにおける視点などを揃える目的があります。

4. 導入

まずは前述のフォーマットを上司とざっくり決めて、パイロット的に自分が書いたものをレビューしてもらうことにしました。この時点ではまだ必須ではなく出来るだけ書きましょうというフェーズでした。

1~2ヶ月経った時点で振り返りを実施しそこそこ手応えを感じ、3~4ヶ月経った時点でチームのみんなが自然に取り組めるようになってました。

最終的に前述のtemplateを元に、プロジェクトが始まったら各自DesignDocを書いてチームレビューに回すというルールを適用しました。

レビューに関しては週に1時間「設計レビューMTG」の時間でシェアしてもらい、チームで議論をしています
事前にDesignDocが準備できている場合はSlackでレビューを依頼してブラッシュアップをしてからMTGに持ち込むこともあります

5. 運用してみて

サービスのドメイン知識が強い人、特定の技術領域が強い人など、メンバーのスキルセットはバラバラなので、1つの設計に対し議論するMTGがあることで良いフィードバックができることが多く、チームに合っていました。

またチームメンバーからの声を抜粋すると、

「設計の抜け漏れ、バグ、負荷、コストにつながる部分は事前に検知出来た」
「ドメインナレッジの平準化、今誰が何してるのか？ということをチーム全体でシェアして、誰が何してるのかよくわからんみたいなことが少なくなった」
「解像度が高い状態で作業に取り書かれる」

などいろいろポジティブな意見をもらうことができました。

一方でタイミングにより、週1のMTGで共有したいDesignDocが渋滞してしまい、なかなかレビューを受けられないということも起きてしまいました。またプロジェクトの説明やデザインの共有などで多くの時間が割かれる場合もあり、共有の方法に課題を感じています。

対策として、小さいプロジェクトは非同期的にレビューをしたり、スポットでMTGを開催したり、議題がない場合はPRDの共有を先んじて行ったり色々試してる最中です。来年はさらにいい形が見つけられたらいいなと思っています。

6. まとめ

定量化出来てるわけではないのですが、感覚値としてDesignDocを導入したことにより、各プロジェクトの設計・アウトプットの質向上が出来たと思います。

さらにフィードバックループを加速させて、設計の質を上げることで、より良いアウトプットをチームとして出していきたいです。

今後の課題として、DesignDocを陳腐化させずに、しっかり仕様のドキュメントとして活きるような、仕組み・改善をしていきたいと思います。

また設計の選択はトレードオフなので、なぜ他の設計を採用しなかったかという背景などの記載も促していきたいです。

これからDesignDocの導入を推進していきたい組織に参考になれば幸いです。