ドキュメント管理の理想と現実

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

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

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

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

例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい

例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい ◦ 例: 関数やモジュールの説明など

例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい ◦ 例: 関数やモジュールの説明など • ソフトウェアの品質を保証したい

例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい ◦ 例: 関数やモジュールの説明など • ソフトウェアの品質を保証したい ◦ 例: テスト計画、テストケース、テスト結果の記録など

例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい ◦ 例: 関数やモジュールの説明など • ソフトウェアの品質を保証したい ◦ 例: テスト計画、テストケース、テスト結果の記録など • プロジェクトを円滑に進めたい ◦ 例: タスク管理方法、リリースフロー、リリース計画、MTG 議事録など

例: アーキテクチャ図、データベース設計、API 仕様書、画面仕様書など • コードの詳細を理解し、追加修正を簡単にしたい ◦ 例: 関数やモジュールの説明など • ソフトウェアの品質を保証したい ◦ 例: テスト計画、テストケース、テスト結果の記録など • プロジェクトを円滑に進めたい ◦ 例: タスク管理方法、リリースフロー、リリース計画、MTG 議事録など • ソフトウェアを適切に使用させたい ◦ 例: インストール手順、操作方法、トラブルシューティング情報など • ..etc

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

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

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

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

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

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

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

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

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

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

© DMM.com 32 具体的にどのように解決しようとしていたか ❷ どのように解決しようとしたか 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 41 • 👍 管理すべきドキュメントが明確になっているから負担が少ない約1年半経った今 (現実) はどうなっているか ❸
理想に対して現実はどうなのか

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

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

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

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

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

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

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

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

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

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

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

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

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

ドキュメント管理の理想と現実

ドキュメント管理の理想と現実

Other Decks in Technology

Featured

Transcript