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
2025-07-06 QGIS初級ハンズオン「はじめてのQGIS」
kou_kita
0
110
Geminiとv0による高速プロトタイピング
shinya337
0
210
ビギナーであり続ける/beginning
ikuodanaka
3
610
250627 関西Ruby会議08 前夜祭 RejectKaigi「DJ on Ruby Ver.0.1」
msykd
PRO
2
430
FrankenPHPでLaravelを動かしてみよう
yousaku
0
100
生まれ変わった AWS Security Hub (Preview) を紹介 #reInforce_osaka / reInforce New Security Hub
masahirokawahara
0
390
生成AI時代の開発組織・技術・プロセス 〜 ログラスの挑戦と考察 〜
itohiro73
1
390
Tech-Verse 2025 Keynote
lycorptech_jp
PRO
0
1.5k
Core Audio tapを使ったリアルタイム音声処理のお話
yuta0306
0
160
【5分でわかる】セーフィー エンジニア向け会社紹介
safie_recruit
0
26k
5min GuardDuty Extended Threat Detection EKS
takakuni
0
180
Yamla: Rustでつくるリアルタイム性を追求した機械学習基盤 / Yamla: A Rust-Based Machine Learning Platform Pursuing Real-Time Capabilities
lycorptech_jp
PRO
4
200
Featured
See All Featured
Building Applications with DynamoDB
mza
95
6.5k
The World Runs on Bad Software
bkeepers
PRO
69
11k
No one is an island. Learnings from fostering a developers community.
thoeni
21
3.4k
What's in a price? How to price your products and services
michaelherold
246
12k
Intergalactic Javascript Robots from Outer Space
tanoku
271
27k
The Art of Delivering Value - GDevCon NA Keynote
reverentgeek
15
1.5k
The Straight Up "How To Draw Better" Workshop
denniskardys
234
140k
Embracing the Ebb and Flow
colly
86
4.7k
CSS Pre-Processors: Stylus, Less & Sass
bermonpainter
357
30k
Principles of Awesome APIs and How to Build Them.
keavy
126
17k
Optimising Largest Contentful Paint
csswizardry
37
3.3k
Building an army of robots
kneath
306
45k
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