Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
Design Doc のすすめ / The Importance of Design Docs
Search
Akira Kuriyama
June 10, 2024
Technology
0
630
Design Doc のすすめ / The Importance of Design Docs
Akira Kuriyama
June 10, 2024
Tweet
Share
More Decks by Akira Kuriyama
See All by Akira Kuriyama
Datadog On-Calを本番導入しました / Datadog On-Cal now in production
sheepland
0
270
Datadog Logsで実現するオブザーバビリティの向上 / Enhancing Observability with Datadog Logs
sheepland
0
140
コンテナ脆弱性修正をRenovate,Dependabotのように行う / Fix Container vulnerabilities on CICD
sheepland
2
440
Docker Build Cloudを導入してコンテナイメージビルド時間を80%削減した話 / Speeding Up Container Builds with Docker Build Cloud
sheepland
0
160
Datadogのグラフにデプロイタイミングを表示する / deploy timing on datadog graph
sheepland
1
680
英語学習の始め方 / How to start learning English
sheepland
0
120
Other Decks in Technology
See All in Technology
「どこから読む?」コードとカルチャーに最速で馴染むための実践ガイド
zozotech
PRO
0
490
Terraformで構築する セルフサービス型データプラットフォーム / terraform-self-service-data-platform
pei0804
1
180
JTCにおける内製×スクラム開発への挑戦〜内製化率95%達成の舞台裏/JTC's challenge of in-house development with Scrum
aeonpeople
0
230
複数サービスを支えるマルチテナント型Batch MLプラットフォーム
lycorptech_jp
PRO
1
590
CDK CLIで使ってたあの機能、CDK Toolkit Libraryではどうやるの?
smt7174
4
190
スマートファクトリーの第一歩 〜AWSマネージドサービスで 実現する予知保全と生成AI活用まで
ganota
2
220
LLM時代のパフォーマンスチューニング:MongoDB運用で試したコンテキスト活用の工夫
ishikawa_pro
0
140
Agile PBL at New Grads Trainings
kawaguti
PRO
1
440
COVESA VSSによる車両データモデルの標準化とAWS IoT FleetWiseの活用
osawa
1
290
ハードウェアとソフトウェアをつなぐ全てを内製している企業の E2E テストの作り方 / How to create E2E tests for a company that builds everything connecting hardware and software in-house
bitkey
PRO
1
150
これでもう迷わない!Jetpack Composeの書き方実践ガイド
zozotech
PRO
0
960
La gouvernance territoriale des données grâce à la plateforme Terreze
bluehats
0
180
Featured
See All Featured
YesSQL, Process and Tooling at Scale
rocio
173
14k
How to Think Like a Performance Engineer
csswizardry
26
1.9k
RailsConf 2023
tenderlove
30
1.2k
Building a Scalable Design System with Sketch
lauravandoore
462
33k
Done Done
chrislema
185
16k
How to Ace a Technical Interview
jacobian
279
23k
Writing Fast Ruby
sferik
628
62k
Building a Modern Day E-commerce SEO Strategy
aleyda
43
7.6k
How GitHub (no longer) Works
holman
315
140k
How to Create Impact in a Changing Tech Landscape [PerfNow 2023]
tammyeverts
53
2.9k
The Pragmatic Product Professional
lauravandoore
36
6.9k
StorybookのUI Testing Handbookを読んだ
zakiyama
31
6.1k
Transcript
Design Doc のすすめ Akira Kuriyama
03 01 02 04 Table of contents Design Docとは? どんなふうに
書くの? Design Docの利点 Design Docへの 疑問
03 01 02 04 Table of contents Design Docとは? どんなふうに
書くの? Design Docの利点 Design Docへの 疑問
Design Docとは? Design Docsは、開発前に作成するドキュメントで、高レベルな実装戦略や設 計の決定事項をまとめ、トレードオフを考慮した文書。 ドキュメントベースで議論することで、変更の背景や方針をレビュアーに理解し やすくするメリットがある。
書く前 書いた後 なんか難しそう… 書くの面倒そう… 最高! とてもよいツール!!
その前に…
こういうことはありませんか? その1: PRレビューが難しいケース でかいPRが急に来た…。 背景や課題がよく分からない な。 他にも解決方法ありそうだけど なんでこの方法選んだんだろう 。 もういいやApproveしちゃお…
こういうことはありませんか? その2: 大きな手戻りが発生するケース もうすぐでリリースできそう! そういえば◦◦のケースって考慮さ れてるっけ? (あ、抜けてた…。設計からやり直し だ…) もっと早く言って
こういうことはありませんか? その3: 中々設計レビューが通らないケース 設計書を書きました!レビューお願いします! そもそも目的ってなんだっけ? ログってちゃんと保存してる? 他にもBっていうイケてるツールあ るんだけど使わないの? セキュリティって大丈夫なの? マジ病む…
こういったケースを Design Docを書くことで防ぐ ことが出来ます!! ※LTなので断言口調ですが、実際にはその時の状況、執筆者の筆のノリ具合、 今いる世界線、その日の体調によります。
03 01 02 04 Table of contents Design Docとは? どんなふうに
書くの? Design Docの利点 Design Docへの 疑問
どうやって書けばいいんだろう Design Docsは設計書や仕様書などの厳格なドキュメントと違って、 ざっくりしたドキュメント。 また、実際にDesign Docをどのように記述すべきかという 明確な指針はありま せん。 なので、いくつかのベストプラクティスやこんな感じに書くのがいいよねというも のがあります。
どうやって書けばいいんだろう Design Docに書くと有効な項目たち(=テンプレート)を紹介します。 しかし、テンプレートの項目を常にすべてを埋める必要はありません 。 あくまでテンプレートなので不要な項目の削除、項目の追加は自由 です。 議論したい箇所が明確である場合は、 特定の項目だけを記載するなどでも問 題はありません。
つまりどういうこと だ!はやく”答え”を 教えてくれ!!
Design Doc Template https://docs.google.com/document/d/1VR2fMiGhs0Out4ZfkE8vqWUEIZ4uI nPztsW7gUK09xE/edit?usp=sharing
03 01 02 04 Table of contents Design Docとは? どんなふうに
書くの? Design Docの利点 Design Docへの 疑問
Design Docの利点 • チーム内で問題や課題を共有でき、認識合わせ ができる • 設計上の問題を早期に特定することで、 手戻りが少なくなる • フォーマットが統一されているため、
見落としがちなポイントを設計時点で検討 できる • コードには現れない、Why not (なぜ別の方法をしなかったのか? )を議論できる • 人事評価に使える(自分の成果物としてアピールしやすい)
03 01 02 04 Table of contents Design Docとは? どんなふうに
書くの? Design Docの利点 Design Docへの 疑問
疑問 その1 Design Docはいつ書けばいいの? まずDesign Docs自体を作成することは、開発を進める上ではオーバヘッドになります。 そのため基本的には、Design Docsを作成するかどうかの決定は、「Design Docsを作成するこ とに伴う労力が作成のメリットを上回るか」というトレードオフで判断
する。 例えば • いくつかの実装案が考えられる、かつどれがベストなのか決めるのが困難なとき • 技術的であったりドメイン的に新規のものや慣れていないものを扱うとき • シニアエンジニアにアーキテクチャの考察をしていただきたいとき
疑問 その2 Design Docをメンテナンスする必要あるの? Design Docで書いたソフトウェアがまだリリースされていないなら Design Docを更新したほうがよ い。 リリース後は更新しなくてよい。
質の高いレビューがされることで精度が高い設計を行うことに重点を置く。 Architecture Decision Records(ADR)のような、その時の意思決定の過程を残すためのツールと して使うのがよいでしょう。
疑問 その3 詳細設計まで書く必要がある? 必ずしも書く必要はない。 ソフトウェア設計における仕様書や設計書とは別物。
書いてみての個人的な感想 • 必要な観点がリストアップされているのでそれに沿って書けば考慮漏れを防ぐことが できる • 項目に沿って書けばいいので非常に楽 • 自身の思考が整理される • 何回か書くことで、いつDesign
Docを書くべきかが掴めそう • テックブログに流用しやすそう
参考 • Google でのデザイン ドキュメント • How to write a
good software design doc • メルカリShopsでのDesign Docs運用について | メルカリエンジニアリング • Design Docs への思い • GoogleのDesign Docsから学ぶソフトウェア設計 - Qiita • 安全安心にソフトウェア開発を行うための Design Doc導入ガイド|面川泰明| note • 【メモ】良いDesign Docs(Software Design Document)を書くためのリソース集