Movatterモバイル変換

[0]ホーム
URL:

$30 off During Our Annual Pro Sale. View Details »
Speaker DeckSpeaker Deck
Speaker Deck

ADRを一年運用してみた/adr_after_a_year

Avatar for Ryo Tomidokoro Ryo Tomidokoro
April 12, 2024

 ADRを一年運用してみた/adr_after_a_year

PHPカンファレンス小田原2024の登壇資料です。

https://fortee.jp/phpconodawara-2024/proposal/56218b4f-b724-4199-82f1-67497501a9ef

ADRとはなにか？
なぜ、導入する必要があるのか？
実際に導入してみて苦労したこと
良かったこと、悪かったこと

Avatar for Ryo Tomidokoro

Ryo Tomidokoro

April 12, 2024
Tweet

More Decks by Ryo Tomidokoro

See All by Ryo Tomidokoro

Other Decks in Programming

See All in Programming

Featured

See All Featured

Transcript

  1. ADRを一年運用してみた @hanhan1978 PHPカンファレンス小田原2024

  2. @hanhan1978 名前 富所 亮 所属 株式会社カオナビ CTO室 BackEnd Re-architecturing Team

    (BERT) 職業 バックエンドエンジニア Blog https://blog.hanhans.net Podcast https://anchor.fm/yokohama-north-am 2

  3. 目次　

  4. 1. ADRとはなにか？ 2. ドキュメントの位置付け 3. ADRの上手な書き方 4. 一年経ってどうなったか 5. まとめ

  5. 1. ADRとはなにか？ 2. ドキュメントの位置付け 3. ADRの上手な書き方 4. 一年経ってどうなったか 5. まとめ

  6. Architectural Decision Records

  7. トレンド ここ数年でジワジワと浸透

  8. 参考1 https://adr.github.io/

  9. 参考2 ソフトウェアアーキテクチャーの基礎 13章「アーキテクチャー決定」

  10. 細かいお作法とかあるけど

  11. ソフトウェアに関連する 決定・経緯を記録しておくもの

  12. 例えばこんな決定・経緯 • メール送信の方式 • ディレクトリ階層 • CIどうしよう？ • ログの方式どうしよう？ •

    決済代行どうする？

  13. ところで

  14. Q 普通の設計資料と何が違うの？

  15. 1. ADRとはなにか？ 2. ドキュメントの位置付け 3. ADRの上手な書き方 4. 一年経ってどうなったか 5. まとめ

  16. 色々な名前の資料 プロジェクトによって、あったりなかったり • 要件定義書 • DesignDoc • ReadME • PRD

    • 謎のMiro、Figma

  17. Q 普通の設計資料と何が違うの？（再）

  18. A. 自分たちで決める必要がある おれたちのADRの位置付けは自分たちで決める

  19. 組織におけるADRの立ち位置は 組織の都合、規模によって変わる

  20. たとえば弊社

  21. 複数チームによるサービス開発 • 複数チームが同じアプリケーションを同時並行で開発 • 一部のチームは異なるアプリケーションを単独で開発

  22. 各チームの固有ドキュメント • リードやPMが選んだツールを使う • 用意するドキュメントは自分たちの開発に必要なもの

  23. このドキュメント群は 良い意味、悪い意味でサイロ化する

  24. 良い意味 • チームはメンバーに最適なツールを自分たちで選定（主体性 • PdMの管理とも関係しておりマネージメントにもつながる • 自分たちが作ろうとする機能に最適化していて効率がいい

  25. 悪い意味 • チーム部外者に読ませる動機がない • チームまたぎでの統一感はない（利点の裏返し） • システム全体の設計を記述するのは不適切

  26. そこでADRを使って チーム横断の情報共有

  27. ADRの役割 • そもそもチームをまたいた情報共有のために用意している • 横軸チームのドキュメント配置場所としても適切

  28. ADRにチームの壁を越えさせる ［引用］チームトポロジー Chapter 5 4つの基本的なチームタイプ

  29. ADRはみんなのドキュメント

  30. 弊社のADR

  31. 弊社のADR

  32. 弊社のADR

  33. 1. ADRとはなにか？ 2. ドキュメントの位置付け 3. ADRの上手な書き方 4. 一年経ってどうなったか 5. まとめ

  34. テンプレートを用意 コピーしてタイトル変えれば叩き台が完成

  35. 統一フォーマットで 認知負荷を下げる

  36. ADRの実例

  37. 弊社でのADR事例1 • チームを横断する決定だったので長年放置されていた • ADRという形で明文化することで問題が具体化できた

  38. 弊社でのADR事例2 • デプロイとリリースを分離する機能トグル • 特に並行開発においてリリースの細かい制御ができて助かる

  39. ADRで大切な内容 • コンテキスト • 決定 • コンプライアンス 放っておいたら失われてしまうコトを記録するんだ！！

  40. ADRを読みやすくする • 読み手を意識 • 抽象から具体へ • 図

  41. ADRを読みやすくする • 読み手を意識 • 抽象から具体へ • 図 読み手はエンジニア以外も含む！ みんなのドキュメント

  42. ADRを読みやすくする • 読み手を意識 • 抽象から具体へ • 図 パッとみて把握できるように！

  43. 良い文章を書くための参考書 考える技術書く技術 : 問題解決力を伸ばすピラミッド原則

  44. 良い文章を書くための参考書 入門 考える技術・書く技術

  45. ADRを読みやすくする • 読み手を意識 • 抽象から具体へ • 図 人間は文章を読まない！

  46. 図の例

  47. 図の例 ときには手書きの図

  48. 上手なドキュメントを書くには とにかく書いて練習！

  49. 1. ADRとはなにか？ 2. ドキュメントの位置付け 3. ADRの上手な書き方 4. 一年経ってどうなったか 5. まとめ

  50. 通し番号で89まで到達 順調に成長中！ 内容はお見せできなくてすまぬ

  51. 広い心で若干の粒度の違いは 受け止めている

  52. 導入前に気づいてなかった利点

  53. 歴の浅いメンバーが横断的同意を得やすい 古参も援助しやすく、新参も使いやすい 🎉🎉🎉🎉　WIN＆WIN　🎉🎉🎉🎉

  54. 成功させるために意識していたこと

  55. 大事にしていたポイント • ADRの位置付けを明確化 • 履歴の取れるWikiを採用 • 公式感を大切に • 記述のハードルを下げる

  56. 過去の失敗経験

  57. アンチパターン • 導入が雑 • Gitによる版管理 • 定型フォーマットが無し • 気軽に見れない

  58. 結局一番大切なこと

  59. 🔥！！情熱！！🔥

  60. 参考文献 Fearless Change アジャイルに効く アイデアを組織に広めるための48のパターン

  61. 1. ADRとはなにか？ 2. ドキュメントの位置付け 3. ADRの上手な書き方 4. 一年経ってどうなったか 5. まとめ

  62. ADRは横断的な経緯・決定の記録

  63. チームを越えられる

  64. ADRはみんなのドキュメント 街の掲示板を目指せ！

  65. もっと事例を聞きたい方は...... https://offers.jp/worker_events/connpass_26

[8]ページ先頭
©2009-2025 Movatter.jp