Share
Embed
ドキュメント管理の理想と現実
“ドキュメントの鮮度を維持する「しくみ化」の方法 CADDi、DMM.com、IVRyの実践例から” に登壇した際の発表資料です。
https://levtechlab.connpass.com/event/346655/
Ohara Kazuhiro
April 23, 2025
Transcript
68 slides
-
© DMM.com 2 合同会社DMM.com デジタルコンテンツ開発本部 動画配信開発部 大原 一浩 2023年に入社し、とある動画配信サービスの刷新プロジェクトにWebフロンエン ドチームのリーダーとして参画している。
GitHub: @kazuhe X: @kazuhe__ -
© DMM.com 7 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか? • システムの概要や構造を理解したい ◦
例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など -
© DMM.com 8 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか? • システムの概要や構造を理解したい ◦
例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい -
© DMM.com 9 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか? • システムの概要や構造を理解したい ◦
例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい ◦ 例: 関数やモジュールの説明など -
© DMM.com 10 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか? • システムの概要や構造を理解したい ◦
例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい ◦ 例: 関数やモジュールの説明など • ソフトウェアの品質を保証したい -
© DMM.com 11 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか? • システムの概要や構造を理解したい ◦
例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい ◦ 例: 関数やモジュールの説明など • ソフトウェアの品質を保証したい ◦ 例: テスト計画、テストケース、テスト結果の記録など -
© DMM.com 12 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか? • システムの概要や構造を理解したい ◦
例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい ◦ 例: 関数やモジュールの説明など • ソフトウェアの品質を保証したい ◦ 例: テスト計画、テストケース、テスト結果の記録など • プロジェクトを円滑に進めたい ◦ 例: タスク管理方法、リリースフロー、リリース計画、MTG 議事録など -
© DMM.com 13 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか? • システムの概要や構造を理解したい ◦
例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい ◦ 例: 関数やモジュールの説明など • ソフトウェアの品質を保証したい ◦ 例: テスト計画、テストケース、テスト結果の記録など • プロジェクトを円滑に進めたい ◦ 例: タスク管理方法、リリースフロー、リリース計画、MTG 議事録など • ソフトウェアを適切に使用させたい ◦ 例: インストール手順、操作方法、トラブルシューティング情報など • ..etc -
© DMM.com 14 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか? • システムの概要や構造を理解したい ◦
例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい ◦ 例: 関数やモジュールの説明など • ソフトウェアの品質を保証したい ◦ 例: テスト計画、テストケース、テスト結果の記録など • プロジェクトを円滑に進めたい ◦ 例: タスク管理方法、リリースフロー、リリース計画、MTG 議事録など • ソフトウェアを適切に使用させたい ◦ 例: インストール手順、操作方法、トラブルシューティング情報など • ..etc 達成したい目的が多く 目的ごとに読む人や書く人や内容が異なる -
© DMM.com 15 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか? • システムの概要や構造を理解したい ◦
例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい ◦ 例: 関数やモジュールの説明など • ソフトウェアの品質を保証したい ◦ 例: テスト計画、テストケース、テスト結果の記録など • プロジェクトを円滑に進めたい ◦ 例: タスク管理方法、リリースフロー、リリース計画、MTG 議事録など • ソフトウェアを適切に使用させたい ◦ 例: インストール手順、操作方法、トラブルシューティング情報など • ..etc 達成したい目的が多く 目的ごとに読む人や書く人や内容が異なる さらに -
© DMM.com 16 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか? • システムの概要や構造を理解したい ◦
例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい ◦ 例: 関数やモジュールの説明など • ソフトウェアの品質を保証したい ◦ 例: テスト計画、テストケース、テスト結果の記録など • プロジェクトを円滑に進めたい ◦ 例: タスク管理方法、リリースフロー、リリース計画、MTG 議事録など • ソフトウェアを適切に使用させたい ◦ 例: インストール手順、操作方法、トラブルシューティング情報など • ..etc 達成したい目的が多く 目的ごとに読む人や書く人や内容が異なる さらに ・情報が新しいこと -
© DMM.com 17 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか? • システムの概要や構造を理解したい ◦
例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい ◦ 例: 関数やモジュールの説明など • ソフトウェアの品質を保証したい ◦ 例: テスト計画、テストケース、テスト結果の記録など • プロジェクトを円滑に進めたい ◦ 例: タスク管理方法、リリースフロー、リリース計画、MTG 議事録など • ソフトウェアを適切に使用させたい ◦ 例: インストール手順、操作方法、トラブルシューティング情報など • ..etc 達成したい目的が多く 目的ごとに読む人や書く人や内容が異なる さらに ・情報が新しいこと ・検索が容易なこと -
© DMM.com 18 ❶ ドキュメント管理の難しさとは ソフトウェア開発における「ドキュメント」は 何を達成しようとしているのか? • システムの概要や構造を理解したい ◦
例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい ◦ 例: 関数やモジュールの説明など • ソフトウェアの品質を保証したい ◦ 例: テスト計画、テストケース、テスト結果の記録など • プロジェクトを円滑に進めたい ◦ 例: タスク管理方法、リリースフロー、リリース計画、MTG 議事録など • ソフトウェアを適切に使用させたい ◦ 例: インストール手順、操作方法、トラブルシューティング情報など • ..etc 達成したい目的が多く 目的ごとに読む人や書く人や内容が異なる さらに ・情報が新しいこと ・検索が容易なこと だ か ら 難 し い -
© DMM.com 31 具体的にどのように 解決しようとしていたか ❷ どのように解決しようとしたか ADR 運用フロー 状況によって柔軟に議論
• 口頭で議論することもあれば • Issueにコメントをしてもらうことも 口頭で議論した場合、なるべくIssueの コメントに残すことで価値のあるADRになる -
© DMM.com 33 具体的にどのように 解決しようとしていたか ❷ どのように解決しようとしたか ADR 運用フロー 否認されたADRも含めると
現在は32個のADRがある (以下例 • インフラ構成概要 • PC/SPデバイス判定方針 • Monorepo構成 • エラーハンドリング設計 • etc. -
© DMM.com 35 具体的にどのように 解決しようとしていたか ❷ どのように解決しようとしたか Issue の種別と関係 上流からの要求など、実現したい
目的そのものを表現した粒度の荒いIssue 開発者目線での作業を単位としたIssue -
© DMM.com 38 ここまでの振り返り ❷ どのように解決しようとしたか 1. ソフトウェア開発において、ドキュメントは何を達成しようとしているのか 2. ドキュメントが達成したいことしたいことはたくさんある
3. さらに、目的を達成するためには情報が新しいこと、検索しやすいことが期待されている 4. これが難しいとされる多くの理由かもしれない 5. では、以下を意識して管理してみるとよいかもしれない a. 情報の鮮度を保つドキュメントを限定する b. 対象の性質に合わせてドキュメントを管理する 6. 1 つの手法として ADR や Issue の種別定義をして楽な管理を目指す -
© DMM.com 39 ここまでの振り返り ❷ どのように解決しようとしたか 1. ソフトウェア開発において、ドキュメントは何を達成しようとしているのか 2. ドキュメントが達成したいことしたいことはたくさんある
3. さらに、目的を達成するためには情報が新しいこと、検索しやすいことが期待されている 4. これが難しいとされる多くの理由かもしれない 5. では、以下を意識して管理してみるとよいかもしれない a. 情報の鮮度を保つドキュメントを限定する b. 対象の性質に合わせてドキュメントを管理する 6. 1 つの手法として ADR や Issue の種別定義をして楽な管理を目指す ここまでが理想 記事を書いてから約1年半... -
© DMM.com 42 • 👍 管理すべきドキュメントが明確になっているから負担が少ない ◦ 👎 ただそれでも更新が大変で古い情報が多々ある 約1年半経った今
(現実) はどうなっているか ❸ 理想に対して現実はどうなのか -
© DMM.com 43 • 👍 管理すべきドキュメントが明確になっているから負担が少ない ◦ 👎 ただそれでも更新が大変で古い情報が多々ある •
👍 プロジェクトに途中から入ったメンバーにADRが好評 ◦ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた 約1年半経った今 (現実) はどうなっているか ❸ 理想に対して現実はどうなのか -
© DMM.com 44 • 👍 管理すべきドキュメントが明確になっているから負担が少ない ◦ 👎 ただそれでも更新が大変で古い情報が多々ある •
👍 プロジェクトに途中から入ったメンバーにADRが好評 ◦ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた • 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ◦ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 約1年半経った今 (現実) はどうなっているか ❸ 理想に対して現実はどうなのか -
© DMM.com 45 • 👍 管理すべきドキュメントが明確になっているから負担が少ない ◦ 👎 ただそれでも更新が大変で古い情報が多々ある •
👍 プロジェクトに途中から入ったメンバーにADRが好評 ◦ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた • 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ◦ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 • 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 約1年半経った今 (現実) はどうなっているか ❸ 理想に対して現実はどうなのか -
© DMM.com 46 • 👍 管理すべきドキュメントが明確になっているから負担が少ない ◦ 👎 ただそれでも更新が大変で古い情報が多々ある •
👍 プロジェクトに途中から入ったメンバーにADRが好評 ◦ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた • 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ◦ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 • 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 約1年半経った今 (現実) はどうなっているか ❸ 理想に対して現実はどうなのか 今 (現実) を受け止め、これからどうしていくか -
© DMM.com 48 • 👍 管理すべきドキュメントが明確になっているから負担が少ない ◦ 👎 ただそれでも更新が大変で古い情報が多々ある •
👍 プロジェクトに途中から入ったメンバーにADRが好評 ◦ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた • 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ◦ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 • 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 反省点をどうして(いる|いく)か ❹ 現実とこれから -
© DMM.com 49 • 👍 管理すべきドキュメントが明確になっているから負担が少ない ◦ 👎 ただそれでも更新が大変で古い情報が多々ある •
👍 プロジェクトに途中から入ったメンバーにADRが好評 ◦ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた • 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ◦ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 • 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 反省点をどうして(いる|いく)か ❹ 現実とこれから -
© DMM.com 50 • 👍 管理すべきドキュメントが明確になっているから負担が少ない ◦ 👎 ただそれでも更新が大変で古い情報が多々ある •
👍 管理すべきドキュメントの量を減らす努力ができた ◦ 例: ESLintなど静的解析で縛れるルールは規約化しない • 👍 プロジェクトに途中から入ったメンバーにADRが好評 ◦ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた • 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ◦ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 • 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 反省点をどうして(いる|いく)か ❹ 現実とこれから ADRは有用だった -
© DMM.com 51 • 👍 管理すべきドキュメントが明確になっているから負担が少ない ◦ 👎 ただそれでも更新が大変で古い情報が多々ある •
👍 管理すべきドキュメントの量を減らす努力ができた ◦ 例: ESLintなど静的解析で縛れるルールは規約化しない • 👍 プロジェクトに途中から入ったメンバーにADRが好評 ◦ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた • 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ◦ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 • 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 反省点をどうして(いる|いく)か ❹ 現実とこれから ADRは有用だった しかし、アーキテクチャの説明などオンボーディングに必要な情報は 鮮度の高い情報として管理しておくべきだった -
© DMM.com 52 • 👍 管理すべきドキュメントが明確になっているから負担が少ない ◦ 👎 ただそれでも更新が大変で古い情報が多々ある •
👍 管理すべきドキュメントの量を減らす努力ができた ◦ 例: ESLintなど静的解析で縛れるルールは規約化しない • 👍 プロジェクトに途中から入ったメンバーにADRが好評 ◦ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた • 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ◦ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 • 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 反省点をどうして(いる|いく)か ❹ 現実とこれから ADRは有用だった しかし、アーキテクチャの説明などオンボーディングに必要な情報は 鮮度の高い情報として管理しておくべきだった AIを使ってADRからドキュメントを作ろう -
© DMM.com 55 • 👍 管理すべきドキュメントが明確になっているから負担が少ない ◦ 👎 ただそれでも更新が大変で古い情報が多々ある •
👍 プロジェクトに途中から入ったメンバーにADRが好評 ◦ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた • 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ◦ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 • 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 反省点をどうして(いる|いく)か ❹ 現実とこれから -
© DMM.com 56 • 👍 管理すべきドキュメントが明確になっているから負担が少ない ◦ 👎 ただそれでも更新が大変で古い情報が多々ある •
👍 管理すべきドキュメントの量を減らす努力ができた ◦ 例: ESLintなど静的解析で縛れるルールは規約化しない • 👍 プロジェクトに途中から入ったメンバーにADRが好評 ◦ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた • 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ◦ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 • 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 反省点をどうして(いる|いく)か ❹ 現実とこれから 人間は怠惰だった -
© DMM.com 57 • 👍 管理すべきドキュメントが明確になっているから負担が少ない ◦ 👎 ただそれでも更新が大変で古い情報が多々ある •
👍 管理すべきドキュメントの量を減らす努力ができた ◦ 例: ESLintなど静的解析で縛れるルールは規約化しない • 👍 プロジェクトに途中から入ったメンバーにADRが好評 ◦ 例: 関連するADRを読んで過去の意思決定を把握したうえで改善提案ができた • 👎 ADRベースだと今現在のアーキテクチャをサクッと理解するのが大変 ◦ 例: 今の構成だけを知りたい場合、余分な情報が多すぎてインプットに時間が必要 • 👎 高い鮮度で保つべき情報を発見した際、ドキュメントに追加するのを忘れる 反省点をどうして(いる|いく)か ❹ 現実とこれから 人間は怠惰だった AIにIssueを作ってもらい、せめてタスク化しておこう -
© DMM.com 61 • AIにドキュメント作成の一部を任せる • AIに面倒なIssue作成を任せる •
まだまだAIを活用しきれていない ◦ 鮮度・質の高いドキュメントを低コストで管理するためAIが必須 ◦ AIにドキュメントの活用とドキュメントの管理をさらに任せていきたい 反省点をどうして(いる|いく)か ❹ 現実とこれから