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
5k
更新”しない”ドキュメント管理 「イミュータブルドキュメントモデル」の実運用
ドキュメント管理を制する 陳腐化を防ぐための実践事例 Lunch LT
https://findy.connpass.com/event/302508/
上記にて登壇した際に利用した資料です。
kosui
December 05, 2023
Tweet
Share
More Decks by kosui
See All by kosui
品質とスピードを両立: TypeScriptの柔軟な型システムをバックエンドで活用する
kosui
8
2.8k
Goのコンパイラをみてみよう 〜iotaを通じて〜 @MCCMMANCC 2019 / dive into go complier with iota
kosui
2
300
Other Decks in Technology
See All in Technology
20241108_CS_LLMMT
shigashiyama
0
250
Oracle Cloud Infrastructureデータベース・クラウド:各バージョンのサポート期間
oracle4engineer
PRO
28
12k
AI機能の開発運用のリアルと今後のリアル
akiroom
0
250
第23回Ques_タイミーにおけるQAチームの在り方 / QA Team in Timee
takeyaqa
0
190
AWS パートナー企業でテクニカルサポートに従事して 3年経ったので思うところをまとめてみた
kazzpapa3
1
220
Microsoft Fabric OneLake の実体について
ryomaru0825
0
190
AWS⼊社という選択肢、⾒えていますか
iwamot
2
1.1k
Railsで4GBのデカ動画ファイルのアップロードと配信、どう実現する?
asflash8
1
210
フルカイテン株式会社 採用資料
fullkaiten
0
40k
地理情報データをデータベースに格納しよう~ GPUを活用した爆速データベース PG-Stromの紹介 ~
sakaik
1
110
Microsoft MVPになる前、なってから/Fukuoka_Tech_Women_Community_1_baba
nina01
0
170
Platform Engineering ことはじめ
oracle4engineer
PRO
8
810
Featured
See All Featured
Fontdeck: Realign not Redesign
paulrobertlloyd
82
5.2k
RailsConf & Balkan Ruby 2019: The Past, Present, and Future of Rails at GitHub
eileencodes
131
33k
Building Adaptive Systems
keathley
38
2.3k
Easily Structure & Communicate Ideas using Wireframe
afnizarnur
191
16k
Let's Do A Bunch of Simple Stuff to Make Websites Faster
chriscoyier
505
140k
CSS Pre-Processors: Stylus, Less & Sass
bermonpainter
356
29k
The Invisible Side of Design
smashingmag
297
50k
The Success of Rails: Ensuring Growth for the Next 100 Years
eileencodes
43
6.8k
Rebuilding a faster, lazier Slack
samanthasiow
79
8.7k
Principles of Awesome APIs and How to Build Them.
keavy
126
17k
How to Think Like a Performance Engineer
csswizardry
20
1.1k
Faster Mobile Websites
deanohume
305
30k
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