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
34
品質とスピードを両立: TypeScriptの柔軟な型システムをバックエンドで活用する
kosui
8
3.1k
Goのコンパイラをみてみよう 〜iotaを通じて〜 @MCCMMANCC 2019 / dive into go complier with iota
kosui
2
310
Other Decks in Technology
See All in Technology
医療業界に特化した音声認識モデル構築のためのアノテーションの実態
thickstem
0
500
AWS Lambdaでサーバレス設計を学ぼう_ベンダーロックインの懸念を超えて-サーバレスの真価を探る
fukuchiiinu
4
940
Flutterアプリを⾃然⾔語で操作する
yukisakai1225
0
210
Sansan Engineering Unit 紹介資料
sansan33
PRO
1
2k
ai bot got sick (abc 2025s version)
kojira
0
140
CSSの最新トレンド Ver.2025
tonkotsuboy_com
11
3.9k
Digitization部 紹介資料
sansan33
PRO
1
4k
Kafka vs. Pulsar: Performance Evaluation by Petabyte-Scale Streaming Platform Providers
lycorptech_jp
PRO
1
320
型システムを知りたい人のための型検査器作成入門
mame
11
1.9k
All About Sansan – for New Global Engineers
sansan33
PRO
1
1.2k
AI Engineering Summit Pre Event LT #10
okaru
2
360
Go Connectへの想い
chiroruxx
0
150
Featured
See All Featured
The Art of Delivering Value - GDevCon NA Keynote
reverentgeek
14
1.5k
jQuery: Nuts, Bolts and Bling
dougneiner
63
7.8k
Chrome DevTools: State of the Union 2024 - Debugging React & Beyond
addyosmani
6
670
The Art of Programming - Codeland 2020
erikaheidi
54
13k
Visualizing Your Data: Incorporating Mongo into Loggly Infrastructure
mongodb
45
9.6k
Sharpening the Axe: The Primacy of Toolmaking
bcantrill
42
2.4k
Product Roadmaps are Hard
iamctodd
PRO
53
11k
Music & Morning Musume
bryan
47
6.6k
Learning to Love Humans: Emotional Interface Design
aarron
273
40k
How GitHub (no longer) Works
holman
314
140k
Designing Experiences People Love
moore
142
24k
Site-Speed That Sticks
csswizardry
9
620
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