なぜソフトウェア開発のドキュメント管理は難しいのか

サムネイル

ドキュメントは何を達成しようとしているのか
なぜドキュメント管理は難しいのか
情報の鮮度を保つドキュメントを限定する
対象の性質に合わせてドキュメントを管理する
具体的な例
- 管理する場所
- 管理方法
最後に
宣伝

この記事は、DMM グループ Advent Calendar 2023 の初日の記事です。執筆を担当しているのは、動画配信開発部で Web フロントエンド開発をしている大原一浩 (@kazuhe) です。

世のソフトウェア開発において、「ドキュメント管理は難しい」という声をよく聞きます。この記事では、なぜドキュメント管理は難しいのかを考え、私たちはどのように解決しようとしているのかを書きたいと思います。一つの意見として見ていただけると幸いです。

ドキュメントは何を達成しようとしているのか

ソフトウェア開発においてドキュメントは、そもそも何を達成するために書くのでしょうか。プロジェクトの規模や開発のフェーズによって違いはあっても、以下のような目的があるかと思います。

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

この他にもたくさんあると思いますが、大小さまざまな目的を達成するためにドキュメントは書かれており、目的ごとに読む人や書く人、また内容も異なります。

さらに、これらのドキュメントは共通して情報が新しいこと、検索しやすいことが期待されます。せっかくあるドキュメントも古く誤った情報であれば意味はなく、むしろ目的達成の逆効果になってしまうこともあります。また、ドキュメントの量が増え意図した情報を検索することが難しくなると、当然目的は達成されません。

なぜドキュメント管理は難しいのか

先に述べたように、我々はさまざまな目的を達成するために、さまざまなドキュメントを大量に書きます。にも関わらず、情報の鮮度を保ちながら、検索が簡単に行えるように文書を構造化して整理しなければなりません。これが難しいとされる多くの理由だと考えます。

このドキュメント管理の「難しさ」を少なくするためにはどのように管理するとよいのでしょうか。全てを完璧に管理しようとせず、以下のことを意識するとよいと考えます。

情報の鮮度を保つドキュメントを限定する
対象の性質に合わせてドキュメントを管理する

それぞれについて、もう少し詳しく書きます。

情報の鮮度を保つドキュメントを限定する

情報の鮮度を保つドキュメントを限定する理由は、読み手が古くなった情報を誤って認識してしまうことを避けるためです。

何度も述べているように、大量にあるドキュメントを全て最新に保つことは非常に難しいです。であれば、せめて古い情報であることを読み手が理解できていれば、古い情報として参考にするだけで最新情報だと誤認するリスクは減らせます。よくストック情報とフロー情報を分けて管理する手法が紹介されていますが、鮮度を保つドキュメント = ストック情報と考えています。

対象の性質に合わせてドキュメントを管理する

素直に考えると、ドキュメントは同じような手続で管理する方が簡単に思えます。極端な例ですが、必ず変更の際にはメンバーのレビューが必要とルールを決めておくなどです。この例のように、多種多様な目的を達成するためのドキュメントを同じように管理すると、管理方法が複雑だった場合は当然ドキュメントの量が増えるにつれて大変になります。

大きな組織では特に、読み手の部署や職種によって閲覧できる (したい) ドキュメントは異なるので、(人によっては当然であると感じることかもしれませんが) 対象の性質に合わせたドキュメント管理を行うべきだと考えます。ただ、ここで注意するべきことは、管理する方法やツールが増えてくると、どこで何がどのように管理されているのか分からなくなります。これを解決するために、プロジェクト単位で最初に読むべき README 的なドキュメントを用意しておき、そこにドキュメント管理ルールが明確に記載されている必要があります。

具体的な例

とあるサービスのリニューアルプロジェクトを下図のような体制で行っています。この図の線はレポート先を表しており、2023年10月時点の大まかな体制です。

2023年10月時点の大まかな体制図 — 2023 年 10 月時点の大まかな体制図

この図の Web フロントエンド開発 に関するドキュメント管理方法を紹介したいと思います。これが正解であるとは思っていないですが、一つの例として見ていただけると幸いです。また、これより以下では、Webフロントエンド開発に関わる開発者を FE 開発者 と呼びます。

管理する場所

同じツールでドキュメント管理をすることが理想でしたが、社内事情で主に二箇所に分けることになりました。ただし、下図のようにツールの使い分けが明確になっていれば、思ったほど苦労せずにドキュメント管理ができています。

FE 開発者以外も読むドキュメントは、社内で広く利用されている Confluence で管理しています。

FE 開発者しか見ないドキュメントについては、ほぼ全て GitHub で管理しています。この時、高い鮮度で保つドキュメントはドキュメント用の専用リポジトリを用意して、Docusaurusで管理しています。このリポジトリだけ、継続的にメンテナンスを必要としており、その他のドキュメントは全てスナップショット (ある日時の状態を記録したもの) として扱います。これによって、開発が進み全体のドキュメント量が増加しても、最新に保つべきドキュメントは少なく、読み手が古くなった情報を誤って認識する可能性が低くなると期待しています。

また、上図はドキュメントの README 的な場所に記載し、各ツールのリンクを一覧にしています。

管理方法

管理する場所ごとに、管理する方法が異なります。これらの管理方法は、各場所の README に記載されています。

ー Confluence

ここには、Webフロントエンド開発者以外も閲覧するようなドキュメントを置いています。プロジェクト固有の情報を多く含むので詳細に書けないのですが、以下のように分けられています。

スペース XX はリニューアルプロジェクトに関するドキュメント
- システムの要件や Web フロントエンドに閉じない仕様書など
スペース YY は FE開発者が所属するグループに関するドキュメント
- FE開発者の紹介や関わっているプロジェクトの紹介など

ー GitHub / ドキュメント用リポジトリ

このリポジトリは可能な限り簡単に更新できることが理想なので、レビューは不要としています。書き手が変更の PR (Pull request) を作成し、 main へマージすると変更内容が Slack に通知されるので、間違った変更が行われた場合や、最新の情報を他のメンバーも把握することができます。

また、このリポジトリが大きくなればなるほど管理が大変になるので、本当に鮮度を高く保つべき情報かを考慮したうえで追加修正することをルールとしています。

ー GitHub / Issue (ADR)

ADR 自体の説明については、他にもよくまとまった記事が多くあるので、ここでは省略します。

継続してメンテナンスをする必要はないものの、極めて重要な意思決定で一度決定すると変更することが大きなコストになるものは、 Issue ラベル ADR を付与し、他 Issue とは異なる特別な方法で管理しています。具体的には、モジュールの責務配置や、ライブラリやフレームワークの決定が対象となり、以下のフローで管理運用しています。

例えば、新しく状態管理ライブラリを導入したいとなったとき、以下の添付画像のような Issue を作成し、チームメンバーに対して ADR を起票したことを伝えます。

必要であれば、事前にメンバーの意見などを拾っておき、その後正式な提案を Issue のコメントに残します。

何か意見や質問があれば、Issue のコメントを追加してもらい、Issue 上で議論をします。口頭で議論した場合は、その内容を Issue コメントに残す努力をしています。このように時系列でコメントを残しておくことで、価値のある ADR になると思っています。

現時点ではチームメンバー全員の承認を必要としており、承認されると Issue 最上部のコメントの結果に、採用されたコメントのリンクを貼ります。その後、簡単に検索できるようにアプリケーションコードを管理するリポジトリの README にリンクを貼り、Issue を Close します。

まだ期間は短いですが、ADR を実際に運用してみて、既存の決定を変更する際の判断材料として役に立ちました。また、チームメンバーや新規参画者、マネージャーからも、どのような観点で意思決定されたか把握できるとの理由から高評価で、議論するコストはあるものの継続していきたいと思っています。

ー GitHub / Issue or PR

今までに登場していないほとんどのドキュメントは Issue または PR に書きます。

Issue は上流からの要求やリニューアル対象となるページを単位とした Epic と、FE開発者目線での作業を単位とした Task という概念に大別しています。この時、Task は必ず任意の Epic を一つ持つルールとなっており、例として下図のような関係となります (執筆時では、GitHub Issue は子 Issue をタスクとして指定 (例: - [ ] #123) することで Issue の関連付けが可能です)。