こんにちは! ソウゾウのSoftware Engineerの@ogataka50です。連載：メルカリShops 開発の裏側 Vol.2の9日目を担当させていただきます。

9日目はメルカリShopsを開発する中でのDesign Docsの運用について紹介させて頂きます。

Design Docsとは

Design DocsとはGoogleなどで取り入れられているシステム設計ドキュメント手法です。開発をする前にプロジェクトの背景や目的、設計、検討した代案などをdocument化します。そしてそれを持って関係者との共有、議論を行うことによって事前に全体を考察し、精度を高め開発後の手戻りを減らすなどが主な目的になります。

例として、GoogleでのDesign Docsについては下記にまとめられています。
Design Docs at Google

メルカリShopsでのDesign Docsのtemplate

Design Docs template

# Overview

A high level summary that every engineer at the company should understand and use to decide if it’s useful for them to read the rest of the doc. It should be 3 paragraphs max.

# Context

A description of the problem at hand, why this project is necessary, what people need to know to assess this project, and how it fits into the technical strategy, product strategy, or the team’s quarterly goals.

# Scope

A description of the scope of this doc.

# Goal

The Goals section should:

– describe the user-driven impact of your project — where your user might be another engineering team or even another technical system
– specify how to measure success using metrics — bonus points if you can link to a dashboard that tracks those metrics

# Non-Goal

Non-Goals are equally important to describe which problems you won’t be fixing so everyone is on the same page.

# Solution / Technical Architecture

Try to walk through a user story to concretize this. Feel free to include many sub-sections and diagrams.
Provide a big picture first, then fill in lots of details. Aim for a world where you can write this, then take a vacation on some deserted island, and another engineer on the team can just read it and implement the solution as you described.

## System Context Diagrams

In many docs a system-context-diagram can be very useful. Such a diagram shows the system as part of the larger technical landscape and allows readers to contextualize the new design given its environment that they are already familiar with.

## APIs

Systems that store data should likely discuss how and in what rough form this happens. Similar to the advice on APIs, and for the same reasons, copy-pasting complete schema definitions should be avoided. Instead focus on the parts that are relevant to the design and its trade-offs.

## Data Storage

Systems that store data should likely discuss how and in what rough form this happens. Similar to the advice on APIs, and for the same reasons, copy-pasting complete schema definitions should be avoided. Instead focus on the parts that are relevant to the design and its trade-offs.

# Alternative Solution

What else did you consider when coming up with the solution above? What are the pros and cons of the alternatives? Have you considered buying a 3rd-party solution — or using an open source one — that solves this problem as opposed to building your own?

# Milestones

A list of measurable checkpoints, so your PM and your manager’s manager can skim it and know roughly when different parts of the project will be done. I encourage you to break the project down into major user-facing milestones if the project is more than 1 month long.

Use calendar dates so you take into account unrelated delays, vacations, meetings, and so on. It should look something like this:

Start Date: June 7, 2018

Milestone 1 — New system MVP running in dark-mode: June 28, 2018

Milestone 2 – Retire old system: July 4th, 2018

End Date: Add feature X, Y, Z to new system: July 14th, 2018

Add an [Update] subsection here if the ETA of some of these milestone changes, so the stakeholders can easily see the most up-to-date estimates.

# Concerns

# Logs

# Security

# Observability

# References

メルカリShopsではGoogleのDesign Docsをベースにしつつ、少しアレンジをしてDesign Docs運用を行っています。
上記をtemplateとしてDesign Docsを作成していますが、これは前述したDesign Docs at GoogleやHow to write a good software design doc の記述を組み合わせて作成しています。それぞれの項目に何を記述するかなどは割愛させて頂き、どのような運用をしているかを紹介します。

メルカリShopsでは2021年7月のプレオープン以降ぐらいから本格的にDesign Docsの運用が始まりました。

どのようなときDesign Docsを書くか

まずもっとも重要な「どのようなときDesign Docsを書くか」ですが、現状明確な基準は設けていません(!?)
明確な基準は設けていませんが、

• 開発完了までに数sprintを要する
• いくつかの実装方法が考えられる
• 技術的であったりドメイン的に新規のものや慣れていないものを扱う

などを含んだ開発を行う際にDesign Docsを作成することが多いです。これはDesign Docs作成を通じて、全体的なarchitectureの考察、代案とのトレードオフを整理するためです。

基本的には、新しいmicroservicesを開発する時に作成するのが一番多いケースですが、こちらも必須にはしていません。その他にも、既存のmicroservicesに新機能を追加する時やCI/CDの機能追加、A/B Testの手法、data migrationのフローなど、用いられるケースは多岐に渡っています。

Design Docsに何を書くか

各項目の詳細はtemplateの通りなので割愛するのですがいくつかピックアップさせてもらいます。

template通りに書く必要はない

冒頭にtemplateを記載したのですが、常にこれらすべてを埋める必要はありません。あくまでtemplateであって不要な項目の削除、項目の追加は自由です。議論したい箇所が明確である場合は、特定の項目だけを記載するなどでも問題はありません。

Goal/Non-Goal section

Goal/Non-Goalはそれぞれ箇条書きで3行以内にまとめるように意識しています。○○の機能を開発、修正する、そしてそれをどう実現するかということをどうしても考えがちですが、Goalを明確にすることでこれから解決すべき問題は適切かを考察することができます。同時にNon-Goalを明確にすることで議論の発散を防ぎ、議論の集約ができます。

またGoal/Non-Goalを明確にできると仕様/技術的なトレードオフを行う際の指標にすることができます。そのためにも可能な限り余計な要素を引き算した項目を記載しています。

e.g.

• Goalは○○のため3rd-party applicationは利用せず、システム実装する。
• Non-Goalは○○のため○○は初期実装のscope外とする。

Alternative Solution section

すでに思い浮かんでいる代案がある時はそれを記載しますが、特に思い浮かんでいない場合でもどうにかして代案を記載するようにしています。現状のインフラの標準とは別の方法で実装
するならどうするか、3rd-party applicationやOpen sourceを利用する場合はどうするかなどから代案をひねり出すようにしています。
それに対してのPros/Consを出すことで元々考えていた案が適切かを再確認することができます。また同様のSaaSなどが存在する場合は公開されているAPIがモデリングなどの参考になるので毎回調査しています。

Design Docsのレビューと承認フロー

こちらもまた重要なDesign Docsのレビューと承認フローですが、現状明確な基準は設けていません(!?)
n人,○○ teamからapproveがない限り、実装開始できないなどの条件も設けていません。
大まかな流れは下記になります。

1. Design Docs作成
2. 開発Team全体にslackで共有。特定のTeam、個人にレビューしてもらいたい時には個別にメンションする
3. Notion上でレビュー、議論を行う。必要に応じて口頭でも議論しDesign Docsを仕上げる。
4. 議論がある程度収束したら作成者がDesign DocsのstatusをAcceptedに更新する
5. 開発開始

開発開始後のDesign Docs

開発開始後のDesign Docsに関してですが原則更新、メンテナンスは行っていません。

メンテナンスをしないことを明記していることの利点としては、将来新しいメンバーがそのDesign Docsを参照した時も最新のDesignではないということが認識できることです。最新のdocumentだと思って見ていたのに、実装とかけ離れているということはよくあることですが、それは最も避けたいことの1つです。

上記の理由から、開発中に変更があった際に、作成者の思考の整理としてDesign Docsを更新することはありますが、必須にはしていません。
また開発終了後に仕様変更があった場合もDesign Docsを更新することはありません。
あくまで開発時のSnapshotとして議論することを最大の目的としています。
開発完了後にはDesign DocsのstatusをArchiveに更新します。

この運用での効用

いくつか特徴的な点を紹介しましたが、共通していることは作成者へDesign Docs作成の障壁を下げるという点だと思います。

Design Docsは作成、レビューなどのコストが発生します。しかし、全体的な整理をせずに、できるところから実装を始めてしまった場合、上手く進んだ時はよいですが、想定外の自体になった時に手戻りが発生したり、最悪スケジュールのために最適ではない実装でその場を切り抜けるという判断しかできない状況に陥ります。また関係者に全体像を共有できていないためにreviewerへの負荷が増えることが往々にして起こります。

Design Docs作成の障壁を下げることで、議論が活発になり、結果的にソウゾウのバリューである「Move Fast」に繋がっていると思います。またそれはリリースして間もないメルカリShopsにもfitしていると感じています。

それでも手戻りが発生したこともありました…

この記事を書いている時に過去のDesign Docsを見返していたのですが、すべてがスムーズに進んだわけではなく、Design Docsを作成した上で開発を進めたのに手戻りが発生したものもありました…

あるプロジェクトでは関係者と議論をした末に決めた方針でも数個Pull requestsを作成した時点で何か様子がおかしいということになり、最終的にはAlternative Solutionに記載していた方針で実装し直しました。
結果だけを見ると手戻りとなるのですが、数個Pull requestsを作った時点で予想していたものと違うと感じ、方向転換できたのもDesign Docsでの議論があったからこそだと思います。

何か新しいことをする際に不確実性があるのは避けられようがありません。Design Docsと実装を往復しながら小刻みに方向転換し実装を進めることは、不確実なものに対してとても有効なアプローチだと感じています。

まとめと今後

以上、メルカリShopsを開発する中でのDesign Docsの運用について紹介させて頂きました。

Design Docs作成の障壁を下げることで実装前での整理、議論を活性化することが出来ていると思いますが、同時に作成者から読み手への配慮することも重要です。作成者が考えを整理し、図など使いつつ簡潔なDesign Docsを書くことができてこそ、読み手と有意義な議論ができると思います。
結果的にDesign Docsというよりはmini design docに近いものになっているかもしれません。

また現状の運用はメルカリShopsはまだリリースして間もないので成り立っており、serviceや組織のフェーズに応じて今後変化していくかもしれません。その際にはまた共有させて頂ければと思います。
少しでも参考になる箇所があれば幸いです。

---

ソウゾウではメンバーを大募集中です。メルカリShopsの開発やソウゾウに興味を持った方がいればぜひご応募お待ちしています。
詳しくは以下のページをご覧ください。

• Software Engineer
• Software Engineer, Site Reliability
• Software Engineer, Machine Learning
• Software Engineer, QA Test
• Software Engineer (Internship) – Mercari Group （※新卒採用に応募するにはまずインターンへの参加をお願いしています。）
  またカジュアルに話だけ聞いてみたい、といった方も大歓迎です。こちらの申し込みフォームよりぜひご連絡ください。