Upgrade to Pro — share decks privately, control downloads, hide ads and more …

更新”しない”ドキュメント管理 「イミュータブルドキュメントモデル」の実運用

kosui
December 05, 2023

更新”しない”ドキュメント管理 「イミュータブルドキュメントモデル」の実運用

ドキュメント管理を制する 陳腐化を防ぐための実践事例 Lunch LT
https://findy.connpass.com/event/302508/

上記にて登壇した際に利用した資料です。

kosui

December 05, 2023
Tweet

More Decks by kosui

Other Decks in Technology

Transcript

  1. 更新

    しない

    ドキュメント管理
    「イミュータブルドキュメントモデル」の実運用
    kosui (@kosui_me)
    1

    View full-size slide

  2. 自己紹介
    X / Twitter:
    @kosui_me
    株式会社カケハシ
    (2022/08-
    現在)
    社内プラットフォームシステムの開発・運用
    認証認可基盤
    組織アカウント管理サービス
    株式会社ディー・エヌ・エー
    (2019/04-2022/08)
    タクシー配車アプリ「GO
    」(
    当時MOV)
    認証認可基盤
    kosui (
    岩佐 幸翠
    )
    2

    View full-size slide

  3. 「現在の仕様や設計」の考古学あるある
    「おや、ここはなぜこの仕様になったんだ」
    何かを意図してこの仕様?
    特に何も考えずこの仕様?
    「こんなに丁寧で詳細なドキュメントが!」
    しかし、よく見ると記事の作成日は古く
    中途半端に更新されているが知りたいことは書いてない
    「結局、何でこの仕様になったの?

    ①謎の仕様を見つける
    ②ドキュメントを探す
    ③何もわからないことが分かる
    3

    View full-size slide

  4. ドキュメントの悪循環
    「じゃあ、最新の仕様・設計とその背景を全部書けばいいんだ!」
    「全ての開発プロセスにドキュメント執筆を義務化して...

    悪貨は良貨を駆逐する
    "
    天才的
    "
    な発想
    4

    View full-size slide

  5. 「最新の仕様・設計」を更新し続けるのは不可能
    5

    View full-size slide

  6. 意思決定に目を向ける
    仕様・設計は変化していくが、それを決めた当時の意思決定は不変
    意思決定の記録は、後から更新する必要がなく、仕様や設計の背景を端的に示せる
    「結局、何でこの仕様になったの?

    最新の仕様・設計は意思決定の積み重ね
    不変である「意思決定」を中心に記録する
    6

    View full-size slide

  7. イミュータブルドキュメントモデル
    イミュータブルデータモデルから影響を受けたドキュメント管理の考え方
    継続して更新すべき「可変なドキュメント」をできるだけ減らし
    それらの元となる意思決定を「不変なドキュメント」として記録する
    「なぜこの仕様にしたのか」「設計にあたって何を検討したのか」という
    重要な情報は後世に残しつつ、ドキュメントの運用負荷を低減させる
    7

    View full-size slide

  8. イミュータブルドキュメントモデル① 不変な情報
    合意したら合意日を明記し、その後は更新しない
    意思決定を不変な情報としてドキュメントにする
    8

    View full-size slide

  9. イミュータブルドキュメントモデル② 可変な情報
    大前提:
    なるべく書かない
    あくまで意思決定の要約として記述
    関連する意思決定を冒頭で明示
    仕様・設計は可変な情報としてドキュメントにする
    9

    View full-size slide

  10. 運用上の課題と解決策
    10

    View full-size slide

  11. 運用上の課題
    11

    View full-size slide

  12. 課題① テンプレ埋めが目的化しがち
    意思決定を記録する上でPRD
    やDesign Doc
    は有用な手法
    しかし、意思決定の規模によってはもっと手軽に書きたい
    例) PRD
    の「競合分析」に「特になし」と書きがち
    ADR
    をベースとした、非常に軽量な意思決定の記録手法
    背景:
    なぜその意思決定を下すか
    決定:
    何を決定したのか
    影響:
    決定による影響は何か
    問題提起の時点で「背景」から記述しチーム内の認識合わせに利用
    MTG
    で「それDR
    にしましょう!」「DR
    書いたらそれベースでMTG
    しましょう」と声掛け
    PRD

    Design Doc
    は目的に対して重厚な時も
    Decision Record
    12

    View full-size slide

  13. 運用事例
    (
    弊チームの場合
    )
    基本的には意思決定をDecision Record
    で記録している
    ディレクトリ構成 比率
    13

    View full-size slide

  14. 課題② 誰がいつレビューしたか分からない
    当初はSlack
    でレビューコメントをしていた
    過去の意思決定の記事は「これ、結局合意したの?してないの?」になりがち
    ドキュメントのテンプレートを変更し
    記事の冒頭にてステータス・承認日・関係者が分かるように
    ステータス 提案中
    承認日 2023/--/--
    関係者
    この意思決定へ合意する場合は

    してください
    PdM
    田中花子 (
    任意)
    エンジニア 山田太郎
    記事の作成日や更新日は
    誤字修正や操作ミスによって更新される
    「意思決定を下した日」を明示すべき
    組織の編成は不変ではないため
    チーム名ではなく個人名を書く
    「この記事にある話、結局どうなったの
    ?

    一目でわかる意思決定のステータス
    14

    View full-size slide

  15. まとめ
    意思決定を記録するハードルを下げる
    軽量なドキュメント手法「Decision Record

    問題提起のタイミングから書き始めて認識合わせに用いる
    意思決定を理解するハードルを下げるため、意思決定のステータスを明示する
    可変なドキュメントはなるべく増やさない
    運用のコツ
    15

    View full-size slide