Tweet
Tweet

Slide 1

Slide 1 text

ドキュメント管理の理想と現実 なぜソフトウェア開発のドキュメント管理は難しいのか 合同会社DMM.com デジタルコンテンツ開発本部 動画配信開発部 大原 一浩

Slide 2

Slide 2 text

© DMM.com 2 合同会社DMM.com デジタルコンテンツ開発本部 動画配信開発部 大原 一浩 2023年に入社し、とある動画配信サービスの刷新プロジェクトにWebフロンエン ドチームのリーダーとして参画している。 GitHub: @kazuhe X: @kazuhe__

Slide 3

Slide 3 text

© DMM.com 3 https://inside.dmm.com/articles/software-documentation-challenges/ アジェンダ 1. ドキュメント管理の難しさとは 2. どのように解決しようとしたか 3. 理想に対して現実はどうなのか 4. 現実とこれから

Slide 4

Slide 4 text

© DMM.com 4 https://inside.dmm.com/articles/software-documentation-challenges/ アジェンダ 1. ドキュメント管理の難しさとは 2. どのように解決しようとしたか 3. 理想に対して現実はどうなのか 4. 現実とこれから

Slide 5

Slide 5 text

© DMM.com 5 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか？

Slide 6

Slide 6 text

© DMM.com 6 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか？ ● システムの概要や構造を理解したい

Slide 7

Slide 7 text

© DMM.com 7 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか？ ● システムの概要や構造を理解したい ○ 例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など

Slide 8

Slide 8 text

© DMM.com 8 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか？ ● システムの概要や構造を理解したい ○ 例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など ● コードの詳細を理解し、追加修正を簡単にしたい

Slide 9

Slide 9 text

© DMM.com 9 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか？ ● システムの概要や構造を理解したい ○ 例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など ● コードの詳細を理解し、追加修正を簡単にしたい ○ 例: 関数やモジュールの説明など

Slide 10

Slide 10 text

© DMM.com 10 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか？ ● システムの概要や構造を理解したい ○ 例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など ● コードの詳細を理解し、追加修正を簡単にしたい ○ 例: 関数やモジュールの説明など ● ソフトウェアの品質を保証したい

Slide 11

Slide 11 text

© DMM.com 11 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか？ ● システムの概要や構造を理解したい ○ 例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など ● コードの詳細を理解し、追加修正を簡単にしたい ○ 例: 関数やモジュールの説明など ● ソフトウェアの品質を保証したい ○ 例: テスト計画、テストケース、テスト結果の記録など

Slide 12

Slide 12 text

© DMM.com 12 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか？ ● システムの概要や構造を理解したい ○ 例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など ● コードの詳細を理解し、追加修正を簡単にしたい ○ 例: 関数やモジュールの説明など ● ソフトウェアの品質を保証したい ○ 例: テスト計画、テストケース、テスト結果の記録など ● プロジェクトを円滑に進めたい ○ 例: タスク管理方法、リリースフロー、リリース計画、MTG 議事録など

Slide 13

Slide 13 text

© DMM.com 13 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか？ ● システムの概要や構造を理解したい ○ 例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など ● コードの詳細を理解し、追加修正を簡単にしたい ○ 例: 関数やモジュールの説明など ● ソフトウェアの品質を保証したい ○ 例: テスト計画、テストケース、テスト結果の記録など ● プロジェクトを円滑に進めたい ○ 例: タスク管理方法、リリースフロー、リリース計画、MTG 議事録など ● ソフトウェアを適切に使用させたい ○ 例: インストール手順、操作方法、トラブルシューティング情報など ● ..etc

Slide 14

Slide 14 text

© DMM.com 14 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか？ ● システムの概要や構造を理解したい ○ 例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など ● コードの詳細を理解し、追加修正を簡単にしたい ○ 例: 関数やモジュールの説明など ● ソフトウェアの品質を保証したい ○ 例: テスト計画、テストケース、テスト結果の記録など ● プロジェクトを円滑に進めたい ○ 例: タスク管理方法、リリースフロー、リリース計画、MTG 議事録など ● ソフトウェアを適切に使用させたい ○ 例: インストール手順、操作方法、トラブルシューティング情報など ● ..etc 達成したい目的が多く 目的ごとに読む人や書く人や内容が異なる

Slide 15

Slide 15 text

© DMM.com 15 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか？ ● システムの概要や構造を理解したい ○ 例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など ● コードの詳細を理解し、追加修正を簡単にしたい ○ 例: 関数やモジュールの説明など ● ソフトウェアの品質を保証したい ○ 例: テスト計画、テストケース、テスト結果の記録など ● プロジェクトを円滑に進めたい ○ 例: タスク管理方法、リリースフロー、リリース計画、MTG 議事録など ● ソフトウェアを適切に使用させたい ○ 例: インストール手順、操作方法、トラブルシューティング情報など ● ..etc 達成したい目的が多く 目的ごとに読む人や書く人や内容が異なる さらに

Slide 16

Slide 16 text

© DMM.com 16 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか？ ● システムの概要や構造を理解したい ○ 例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など ● コードの詳細を理解し、追加修正を簡単にしたい ○ 例: 関数やモジュールの説明など ● ソフトウェアの品質を保証したい ○ 例: テスト計画、テストケース、テスト結果の記録など ● プロジェクトを円滑に進めたい ○ 例: タスク管理方法、リリースフロー、リリース計画、MTG 議事録など ● ソフトウェアを適切に使用させたい ○ 例: インストール手順、操作方法、トラブルシューティング情報など ● ..etc 達成したい目的が多く 目的ごとに読む人や書く人や内容が異なる さらに ・情報が新しいこと

Slide 17

Slide 17 text

© DMM.com 17 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか？ ● システムの概要や構造を理解したい ○ 例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など ● コードの詳細を理解し、追加修正を簡単にしたい ○ 例: 関数やモジュールの説明など ● ソフトウェアの品質を保証したい ○ 例: テスト計画、テストケース、テスト結果の記録など ● プロジェクトを円滑に進めたい ○ 例: タスク管理方法、リリースフロー、リリース計画、MTG 議事録など ● ソフトウェアを適切に使用させたい ○ 例: インストール手順、操作方法、トラブルシューティング情報など ● ..etc 達成したい目的が多く 目的ごとに読む人や書く人や内容が異なる さらに ・情報が新しいこと ・検索が容易なこと

Slide 18

Slide 18 text

© DMM.com 18 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか？ ● システムの概要や構造を理解したい ○ 例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など ● コードの詳細を理解し、追加修正を簡単にしたい ○ 例: 関数やモジュールの説明など ● ソフトウェアの品質を保証したい ○ 例: テスト計画、テストケース、テスト結果の記録など ● プロジェクトを円滑に進めたい ○ 例: タスク管理方法、リリースフロー、リリース計画、MTG 議事録など ● ソフトウェアを適切に使用させたい ○ 例: インストール手順、操作方法、トラブルシューティング情報など ● ..etc 達成したい目的が多く 目的ごとに読む人や書く人や内容が異なる さらに ・情報が新しいこと ・検索が容易なこと だ か ら 難 し い

Slide 19

Slide 19 text

© DMM.com 19 https://inside.dmm.com/articles/software-documentation-challenges/ アジェンダ 1. ドキュメント管理の難しさとは 2. どのように解決しようとしたか 3. 理想に対して現実はどうなのか 4. 現実とこれから

Slide 20

Slide 20 text

© DMM.com 20 ❷ どのように解決しようとしたか ドキュメント管理の「難しさ」を どのように減らすか

Slide 21

Slide 21 text

© DMM.com 21 ● 情報の鮮度を保つドキュメントを限定する ● 対象の性質に合わせてドキュメントを管理する ドキュメント管理の「難しさ」を どのように減らすか ❷ どのように解決しようとしたか

Slide 22

Slide 22 text

© DMM.com 22 ● 情報の鮮度を保つドキュメントを限定する ● 対象の性質に合わせてドキュメントを管理する ドキュメント管理の「難しさ」を どのように減らすか ❷ どのように解決しようとしたか

Slide 23

Slide 23 text

© DMM.com 23 具体的にどのように 解決しようとしていたか ❷ どのように解決しようとしたか ※2023年10月時点の大まかな体制 (当時よりも人数は増えている とある動画配信サービスの刷新プロジェクトの概要

Slide 24

Slide 24 text

© DMM.com 24 具体的にどのように 解決しようとしていたか ❷ どのように解決しようとしたか 読み手は誰か？ プロジェクト特有ではない情報 (1on1ログやグループの目標など)

Slide 25

Slide 25 text

© DMM.com 25 具体的にどのように 解決しようとしていたか ❷ どのように解決しようとしたか 重要 スナップショット (ある時点の状態の記録) として扱う

Slide 26

Slide 26 text

© DMM.com 26 具体的にどのように 解決しようとしていたか ❷ どのように解決しようとしたか 一度決定すると変更することが 大きなコストになるもの モジュールの責務配置、 ライブラリやフレームワークの決定・変更など

Slide 27

Slide 27 text

© DMM.com 27 具体的にどのように 解決しようとしていたか ❷ どのように解決しようとしたか ADR 運用フロー

Slide 28

Slide 28 text

© DMM.com 28 具体的にどのように 解決しようとしていたか ❷ どのように解決しようとしたか ADR 運用フロー

Slide 29

Slide 29 text

© DMM.com 29

Slide 30

Slide 30 text

© DMM.com 30

Slide 31

Slide 31 text

© DMM.com 31 具体的にどのように 解決しようとしていたか ❷ どのように解決しようとしたか ADR 運用フロー 状況によって柔軟に議論 ● 口頭で議論することもあれば ● Issueにコメントをしてもらうことも 口頭で議論した場合、なるべくIssueの コメントに残すことで価値のあるADRになる

Slide 32

Slide 32 text

© DMM.com 32 具体的にどのように 解決しようとしていたか ❷ どのように解決しようとしたか ADR 運用フロー 記事執筆当時は全員の承認を必要としてい たが、現在はチームの過半数以上

Slide 33

Slide 33 text

© DMM.com 33 具体的にどのように 解決しようとしていたか ❷ どのように解決しようとしたか ADR 運用フロー 否認されたADRも含めると 現在は32個のADRがある (以下例 ● インフラ構成概要 ● PC/SPデバイス判定方針 ● Monorepo構成 ● エラーハンドリング設計 ● etc.

Slide 34

Slide 34 text

© DMM.com 34 具体的にどのように 解決しようとしていたか ❷ どのように解決しようとしたか 詳細設計や実装時の課題など

Slide 35

Slide 35 text

© DMM.com 35 具体的にどのように 解決しようとしていたか ❷ どのように解決しようとしたか Issue の種別と関係 上流からの要求など、実現したい 目的そのものを表現した粒度の荒いIssue 開発者目線での作業を単位としたIssue

Slide 36

Slide 36 text

© DMM.com 36 具体的にどのように 解決しようとしていたか ❷ どのように解決しようとしたか (余談) GitHubにSub-issue機能が追加され、EpicとTaskの紐付けが簡単明快になった

Slide 37

Slide 37 text

© DMM.com 37 GitHubはMermaidを使うことができるので、 IssueやPRでもある程度の表現ができる 具体的にどのように 解決しようとしていたか ❷ どのように解決しようとしたか

Slide 38

Slide 38 text

© DMM.com 38 ここまでの振り返り ❷ どのように解決しようとしたか 1. ソフトウェア開発において、ドキュメントは何を達成しようとしているのか 2. ドキュメントが達成したいことしたいことはたくさんある 3. さらに、目的を達成するためには情報が新しいこと、検索しやすいことが期待されている 4. これが難しいとされる多くの理由かもしれない 5. では、以下を意識して管理してみるとよいかもしれない a. 情報の鮮度を保つドキュメントを限定する b. 対象の性質に合わせてドキュメントを管理する 6. 1 つの手法として ADR や Issue の種別定義をして楽な管理を目指す

Slide 39

Slide 39 text

© DMM.com 39 ここまでの振り返り ❷ どのように解決しようとしたか 1. ソフトウェア開発において、ドキュメントは何を達成しようとしているのか 2. ドキュメントが達成したいことしたいことはたくさんある 3. さらに、目的を達成するためには情報が新しいこと、検索しやすいことが期待されている 4. これが難しいとされる多くの理由かもしれない 5. では、以下を意識して管理してみるとよいかもしれない a. 情報の鮮度を保つドキュメントを限定する b. 対象の性質に合わせてドキュメントを管理する 6. 1 つの手法として ADR や Issue の種別定義をして楽な管理を目指す ここまでが理想 記事を書いてから約1年半...

Slide 40

Slide 40 text

© DMM.com 40 https://inside.dmm.com/articles/software-documentation-challenges/ アジェンダ 1. ドキュメント管理の難しさとは 2. どのように解決しようとしたか 3. 理想に対して現実はどうなのか 4. 現実とこれから

Slide 41

Slide 41 text

© DMM.com 41 ● 👍 管理すべきドキュメントが明確になっているから負担が少ない 約1年半経った今 (現実) はどうなっているか ❸ 理想に対して現実はどうなのか

Slide 42

Slide 42 text

© DMM.com 42 ● 👍 管理すべきドキュメントが明確になっているから負担が少ない ○ 👎 ただそれでも更新が大変で古い情報が多々ある 約1年半経った今 (現実) はどうなっているか ❸ 理想に対して現実はどうなのか

Slide 43

Slide 43 text

© DMM.com 43 ● 👍 管理すべきドキュメントが明確になっているから負担が少ない ○ 👎 ただそれでも更新が大変で古い情報が多々ある ● 👍 プロジェクトに途中から入ったメンバーにADRが好評 ○ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた 約1年半経った今 (現実) はどうなっているか ❸ 理想に対して現実はどうなのか

Slide 44

Slide 44 text

© DMM.com 44 ● 👍 管理すべきドキュメントが明確になっているから負担が少ない ○ 👎 ただそれでも更新が大変で古い情報が多々ある ● 👍 プロジェクトに途中から入ったメンバーにADRが好評 ○ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた ● 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ○ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 約1年半経った今 (現実) はどうなっているか ❸ 理想に対して現実はどうなのか

Slide 45

Slide 45 text

© DMM.com 45 ● 👍 管理すべきドキュメントが明確になっているから負担が少ない ○ 👎 ただそれでも更新が大変で古い情報が多々ある ● 👍 プロジェクトに途中から入ったメンバーにADRが好評 ○ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた ● 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ○ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 ● 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 約1年半経った今 (現実) はどうなっているか ❸ 理想に対して現実はどうなのか

Slide 46

Slide 46 text

© DMM.com 46 ● 👍 管理すべきドキュメントが明確になっているから負担が少ない ○ 👎 ただそれでも更新が大変で古い情報が多々ある ● 👍 プロジェクトに途中から入ったメンバーにADRが好評 ○ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた ● 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ○ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 ● 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 約1年半経った今 (現実) はどうなっているか ❸ 理想に対して現実はどうなのか 今 (現実) を受け止め、これからどうしていくか

Slide 47

Slide 47 text

© DMM.com 47 https://inside.dmm.com/articles/software-documentation-challenges/ アジェンダ 1. ドキュメント管理の難しさとは 2. どのように解決しようとしたか 3. 理想に対して現実はどうなのか 4. 現実とこれから

Slide 48

Slide 48 text

© DMM.com 48 ● 👍 管理すべきドキュメントが明確になっているから負担が少ない ○ 👎 ただそれでも更新が大変で古い情報が多々ある ● 👍 プロジェクトに途中から入ったメンバーにADRが好評 ○ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた ● 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ○ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 ● 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 反省点をどうして(いる|いく)か ❹ 現実とこれから

Slide 49

Slide 49 text

© DMM.com 49 ● 👍 管理すべきドキュメントが明確になっているから負担が少ない ○ 👎 ただそれでも更新が大変で古い情報が多々ある ● 👍 プロジェクトに途中から入ったメンバーにADRが好評 ○ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた ● 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ○ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 ● 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 反省点をどうして(いる|いく)か ❹ 現実とこれから

Slide 50

Slide 50 text

© DMM.com 50 ● 👍 管理すべきドキュメントが明確になっているから負担が少ない ○ 👎 ただそれでも更新が大変で古い情報が多々ある ● 👍 管理すべきドキュメントの量を減らす努力ができた ○ 例: ESLintなど静的解析で縛れるルールは規約化しない ● 👍 プロジェクトに途中から入ったメンバーにADRが好評 ○ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた ● 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ○ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 ● 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 反省点をどうして(いる|いく)か ❹ 現実とこれから ADRは有用だった

Slide 51

Slide 51 text

© DMM.com 51 ● 👍 管理すべきドキュメントが明確になっているから負担が少ない ○ 👎 ただそれでも更新が大変で古い情報が多々ある ● 👍 管理すべきドキュメントの量を減らす努力ができた ○ 例: ESLintなど静的解析で縛れるルールは規約化しない ● 👍 プロジェクトに途中から入ったメンバーにADRが好評 ○ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた ● 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ○ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 ● 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 反省点をどうして(いる|いく)か ❹ 現実とこれから ADRは有用だった しかし、アーキテクチャの説明などオンボーディングに必要な情報は 鮮度の高い情報として管理しておくべきだった

Slide 52

Slide 52 text

© DMM.com 52 ● 👍 管理すべきドキュメントが明確になっているから負担が少ない ○ 👎 ただそれでも更新が大変で古い情報が多々ある ● 👍 管理すべきドキュメントの量を減らす努力ができた ○ 例: ESLintなど静的解析で縛れるルールは規約化しない ● 👍 プロジェクトに途中から入ったメンバーにADRが好評 ○ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた ● 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ○ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 ● 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 反省点をどうして(いる|いく)か ❹ 現実とこれから ADRは有用だった しかし、アーキテクチャの説明などオンボーディングに必要な情報は 鮮度の高い情報として管理しておくべきだった AIを使ってADRからドキュメントを作ろう

Slide 53

Slide 53 text

© DMM.com 53

Slide 54

Slide 54 text

© DMM.com 54

Slide 55

Slide 55 text

© DMM.com 55 ● 👍 管理すべきドキュメントが明確になっているから負担が少ない ○ 👎 ただそれでも更新が大変で古い情報が多々ある ● 👍 プロジェクトに途中から入ったメンバーにADRが好評 ○ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた ● 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ○ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 ● 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 反省点をどうして(いる|いく)か ❹ 現実とこれから

Slide 56

Slide 56 text

© DMM.com 56 ● 👍 管理すべきドキュメントが明確になっているから負担が少ない ○ 👎 ただそれでも更新が大変で古い情報が多々ある ● 👍 管理すべきドキュメントの量を減らす努力ができた ○ 例: ESLintなど静的解析で縛れるルールは規約化しない ● 👍 プロジェクトに途中から入ったメンバーにADRが好評 ○ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた ● 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ○ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 ● 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 反省点をどうして(いる|いく)か ❹ 現実とこれから 人間は怠惰だった

Slide 57

Slide 57 text

© DMM.com 57 ● 👍 管理すべきドキュメントが明確になっているから負担が少ない ○ 👎 ただそれでも更新が大変で古い情報が多々ある ● 👍 管理すべきドキュメントの量を減らす努力ができた ○ 例: ESLintなど静的解析で縛れるルールは規約化しない ● 👍 プロジェクトに途中から入ったメンバーにADRが好評 ○ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた ● 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ○ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 ● 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 反省点をどうして(いる|いく)か ❹ 現実とこれから 人間は怠惰だった AIにIssueを作ってもらい、せめてタスク化しておこう

Slide 58

Slide 58 text

© DMM.com 58

Slide 59

Slide 59 text

© DMM.com 59

Slide 60

Slide 60 text

© DMM.com 60

Slide 61

Slide 61 text

© DMM.com 61 ● 󰢏 AIにドキュメント作成の一部を任せる ● 󰢏 AIに面倒なIssue作成を任せる ● 󰢄 まだまだAIを活用しきれていない ○ 鮮度・質の高いドキュメントを低コストで管理するためAIが必須 ○ AIにドキュメントの活用とドキュメントの管理をさらに任せていきたい 反省点をどうして(いる|いく)か ❹ 現実とこれから

Slide 62

Slide 62 text

© DMM.com 62 AIにコーディング規約を参照させてコードレビューをさせる ⓿ 番外編 ドキュメントのAI活用 (時間があれば..)

Slide 63

Slide 63 text

© DMM.com 63 AIにコーディング規約を参照させてコードレビューをさせる ⓿ 番外編 ドキュメントのAI活用

Slide 64

Slide 64 text

© DMM.com 64 AIにコーディング規約を参照させてコードレビューをさせる ⓿ 番外編 ドキュメントのAI活用

Slide 65

Slide 65 text

© DMM.com 65 AIにコーディング規約を参照させてコードレビューをさせる ⓿ 番外編 ドキュメントのAI活用

Slide 66

Slide 66 text

© DMM.com 66

Slide 67

Slide 67 text

© DMM.com 67 トークン長の上限に達しているのか、PR全体に対して 量のあるコーディング規約に準拠しているかの確認は現状苦手そう あらかじめコーディング規約を要約してAIにレビュー観点として指示しておくことで回避

Slide 68

Slide 68 text

ドキュメント管理の理想と現実 なぜソフトウェア開発のドキュメント管理は難しいのか 合同会社DMM.com デジタルコンテンツ開発本部 動画配信開発部 大原 一浩