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.7k
更新”しない”ドキュメント管理 「イミュータブルドキュメントモデル」の実運用
ドキュメント管理を制する 陳腐化を防ぐための実践事例 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
56
品質とスピードを両立: 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
フレームワークを意識させないワークショップづくり
keigosuda
0
200
ニッポンの人に知ってもらいたいGISスポット
sakaik
0
150
Contract One Engineering Unit 紹介資料
sansan33
PRO
0
8.8k
業務効率化をさらに加速させる、ノーコードツールとStep Functionsのハイブリッド化
smt7174
2
140
『バイトル』CTOが語る! AIネイティブ世代と切り拓くモノづくり組織
dip_tech
PRO
1
130
「使い方教えて」「事例教えて」じゃもう遅い! Microsoft 365 Copilot を触り倒そう!
taichinakamura
0
410
技育祭2025【秋】 企業ピッチ/登壇資料(高橋 悟生)
hacobu
PRO
0
110
生成AI時代のセキュアコーディングとDevSecOps
yuriemori
0
120
速習AGENTS.md:5分で精度を上げる "3ブロック" テンプレ
ismk
6
1.7k
20251007: What happens when multi-agent systems become larger? (CyberAgent, Inc)
ornew
1
310
能登半島地震で見えた災害対応の課題と組織変革の重要性
ditccsugii
0
1k
衛星画像超解像化によって実現する2D, 3D空間情報の即時生成と“AI as a Service”/ Real-time generation spatial data enabled_by satellite image super-resolution
lehupa
0
170
Featured
See All Featured
10 Git Anti Patterns You Should be Aware of
lemiorhan
PRO
657
61k
How STYLIGHT went responsive
nonsquared
100
5.8k
Rebuilding a faster, lazier Slack
samanthasiow
84
9.2k
Performance Is Good for Brains [We Love Speed 2024]
tammyeverts
12
1.2k
The Myth of the Modular Monolith - Day 2 Keynote - Rails World 2024
eileencodes
26
3.1k
Chrome DevTools: State of the Union 2024 - Debugging React & Beyond
addyosmani
9
910
Building an army of robots
kneath
306
46k
Become a Pro
speakerdeck
PRO
29
5.6k
Leading Effective Engineering Teams in the AI Era
addyosmani
7
460
The Straight Up "How To Draw Better" Workshop
denniskardys
238
140k
A better future with KSS
kneath
239
18k
Rails Girls Zürich Keynote
gr2m
95
14k
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