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
更新”しない”ドキュメント管理 「イミュータブルドキュメントモデル」の実運用
Search
kosui
December 05, 2023
Technology
19
5.5k
更新”しない”ドキュメント管理 「イミュータブルドキュメントモデル」の実運用
ドキュメント管理を制する 陳腐化を防ぐための実践事例 Lunch LT
https://findy.connpass.com/event/302508/
上記にて登壇した際に利用した資料です。
kosui
December 05, 2023
Tweet
Share
More Decks by kosui
See All by kosui
PdMのためのソフトウェアエンジニアリング入門
kosui
0
40
品質とスピードを両立: TypeScriptの柔軟な型システムをバックエンドで活用する
kosui
8
3.1k
Goのコンパイラをみてみよう 〜iotaを通じて〜 @MCCMMANCC 2019 / dive into go complier with iota
kosui
2
320
Other Decks in Technology
See All in Technology
CDK Vibe Coding Fes
tomoki10
1
630
CDK Toolkit Libraryにおけるテストの考え方
smt7174
1
550
本当にわかりやすいAIエージェント入門
segavvy
1
300
QuickSight SPICE の効果的な運用戦略~S3 + Athena 構成での実践ノウハウ~/quicksight-spice-s3-athena-best-practices
emiki
0
290
SRE with AI:実践から学ぶ、運用課題解決と未来への展望
yoshiiryo1
0
300
セキュアな社内Dify運用と外部連携の両立 ~AIによるAPIリスク評価~
zozotech
PRO
0
120
SRE不在の開発チームが障害対応と 向き合った100日間 / 100 days dealing with issues without SREs
shin1988
2
2k
american aa airlines®️ USA Contact Numbers: Complete 2025 Support Guide
aaguide
0
500
AI エージェントと考え直すデータ基盤
na0
20
7.9k
LIXIL基幹システム刷新に立ち向かう技術的アプローチについて
tsukuha
1
380
伴走から自律へ: 形式知へと導くSREイネーブリングによる プロダクトチームの信頼性オーナーシップ向上 / SRE NEXT 2025
visional_engineering_and_design
3
460
全部AI、全員Cursor、ドキュメント駆動開発 〜DevinやGeminiも添えて〜
rinchsan
10
5.1k
Featured
See All Featured
Templates, Plugins, & Blocks: Oh My! Creating the theme that thinks of everything
marktimemedia
31
2.4k
Creating an realtime collaboration tool: Agile Flush - .NET Oxford
marcduiker
30
2.2k
How GitHub (no longer) Works
holman
314
140k
"I'm Feeling Lucky" - Building Great Search Experiences for Today's Users (#IAC19)
danielanewman
229
22k
Responsive Adventures: Dirty Tricks From The Dark Corners of Front-End
smashingmag
251
21k
Refactoring Trust on Your Teams (GOTO; Chicago 2020)
rmw
34
3.1k
Easily Structure & Communicate Ideas using Wireframe
afnizarnur
194
16k
How to Think Like a Performance Engineer
csswizardry
25
1.7k
The MySQL Ecosystem @ GitHub 2015
samlambert
251
13k
Connecting the Dots Between Site Speed, User Experience & Your Business [WebExpo 2025]
tammyeverts
8
340
Optimizing for Happiness
mojombo
379
70k
The Language of Interfaces
destraynor
158
25k
Transcript
更新 ” しない ” ドキュメント管理 「イミュータブルドキュメントモデル」の実運用 kosui (@kosui_me) 1
自己紹介 X / Twitter: @kosui_me 株式会社カケハシ (2022/08- 現在) 社内プラットフォームシステムの開発・運用 認証認可基盤
組織アカウント管理サービス 株式会社ディー・エヌ・エー (2019/04-2022/08) タクシー配車アプリ「GO 」( 当時MOV) 認証認可基盤 kosui ( 岩佐 幸翠 ) 2
「現在の仕様や設計」の考古学あるある 「おや、ここはなぜこの仕様になったんだ」 何かを意図してこの仕様? 特に何も考えずこの仕様? 「こんなに丁寧で詳細なドキュメントが!」 しかし、よく見ると記事の作成日は古く 中途半端に更新されているが知りたいことは書いてない 「結局、何でこの仕様になったの? 」 ①謎の仕様を見つける
②ドキュメントを探す ③何もわからないことが分かる 3
ドキュメントの悪循環 「じゃあ、最新の仕様・設計とその背景を全部書けばいいんだ!」 「全ての開発プロセスにドキュメント執筆を義務化して... 」 悪貨は良貨を駆逐する " 天才的 " な発想 4
「最新の仕様・設計」を更新し続けるのは不可能 5
意思決定に目を向ける 仕様・設計は変化していくが、それを決めた当時の意思決定は不変 意思決定の記録は、後から更新する必要がなく、仕様や設計の背景を端的に示せる 「結局、何でこの仕様になったの? 」 最新の仕様・設計は意思決定の積み重ね 不変である「意思決定」を中心に記録する 6
イミュータブルドキュメントモデル イミュータブルデータモデルから影響を受けたドキュメント管理の考え方 継続して更新すべき「可変なドキュメント」をできるだけ減らし それらの元となる意思決定を「不変なドキュメント」として記録する 「なぜこの仕様にしたのか」「設計にあたって何を検討したのか」という 重要な情報は後世に残しつつ、ドキュメントの運用負荷を低減させる 7
イミュータブルドキュメントモデル① 不変な情報 合意したら合意日を明記し、その後は更新しない 意思決定を不変な情報としてドキュメントにする 8
イミュータブルドキュメントモデル② 可変な情報 大前提: なるべく書かない あくまで意思決定の要約として記述 関連する意思決定を冒頭で明示 仕様・設計は可変な情報としてドキュメントにする 9
運用上の課題と解決策 10
運用上の課題 11
課題① テンプレ埋めが目的化しがち 意思決定を記録する上でPRD やDesign Doc は有用な手法 しかし、意思決定の規模によってはもっと手軽に書きたい 例) PRD の「競合分析」に「特になし」と書きがち
ADR をベースとした、非常に軽量な意思決定の記録手法 背景: なぜその意思決定を下すか 決定: 何を決定したのか 影響: 決定による影響は何か 問題提起の時点で「背景」から記述しチーム内の認識合わせに利用 MTG で「それDR にしましょう!」「DR 書いたらそれベースでMTG しましょう」と声掛け PRD や Design Doc は目的に対して重厚な時も Decision Record 12
運用事例 ( 弊チームの場合 ) 基本的には意思決定をDecision Record で記録している ディレクトリ構成 比率 13
課題② 誰がいつレビューしたか分からない 当初はSlack でレビューコメントをしていた 過去の意思決定の記事は「これ、結局合意したの?してないの?」になりがち ドキュメントのテンプレートを変更し 記事の冒頭にてステータス・承認日・関係者が分かるように ステータス 提案中 承認日
2023/--/-- 関係者 この意思決定へ合意する場合は ☑ してください PdM 田中花子 ( 任意) エンジニア 山田太郎 記事の作成日や更新日は 誤字修正や操作ミスによって更新される 「意思決定を下した日」を明示すべき 組織の編成は不変ではないため チーム名ではなく個人名を書く 「この記事にある話、結局どうなったの ? 」 一目でわかる意思決定のステータス 14
まとめ 意思決定を記録するハードルを下げる 軽量なドキュメント手法「Decision Record 」 問題提起のタイミングから書き始めて認識合わせに用いる 意思決定を理解するハードルを下げるため、意思決定のステータスを明示する 可変なドキュメントはなるべく増やさない 運用のコツ 15