6-4 ドキュメント管理

1. ドキュメントの重要性

1.1 なぜドキュメントが必要か

「コードがドキュメントだ」という主張もあるが、 コードだけではシステムの全体像や意思決定の経緯は伝わらない。 ドキュメントは、チーム間のコミュニケーション、 後任者への引き継ぎ、監査対応など、多くの場面で必要となる。

1.2 ドキュメントの種類

システム開発では、フェーズごとに様々なドキュメントが作成される。 すべてを詳細に作成する必要はないが、 プロジェクトの特性に応じて必要なものを選択し、 適切な粒度で作成・維持することが重要である。

2. ドキュメント管理のベストプラクティス

2.1 管理の原則

ドキュメント管理で最も重要なのは「見つけられること」と「最新であること」である。 どれだけ良いドキュメントを作成しても、 必要な時に見つけられなければ意味がない。 また、古い情報は誤った判断を招く危険性がある。

2.2 管理ツール

ドキュメント管理ツールは、組織の規模や文化に合わせて選択する。 重要なのはツールそのものではなく、 チーム全員がそのツールを使う習慣を定着させることである。

3. Docs as Code

3.1 Docs as Codeとは

Docs as Codeは、ドキュメントをソースコードと同様に管理する考え方である。 Gitでバージョン管理し、CI/CDでビルド・公開する。 コードの変更とドキュメントの変更を同じプルリクエストに含めることで、 ドキュメントの陳腐化を防ぐことができる。

3.2 ツールチェーン

Docs as Codeを実現するためのツールは多数存在する。 Markdownで記述し、静的サイトジェネレーターでHTMLに変換、 CIパイプラインで自動デプロイという流れが一般的である。

4. アーキテクチャ決定記録（ADR）

4.1 ADRとは

ADR（Architecture Decision Record）は、 重要な設計・技術判断を記録する軽量なドキュメント形式である。 なぜその決定をしたのかの経緯を残すことで、 後から振り返った時に「なぜこうなっているのか」を理解できる。

ADRは、プロジェクトのdocsディレクトリに連番で保存する。 例えば「ADR-001: PostgreSQLをデータベースとして採用」のように、 番号とタイトルでファイル名を付ける。 一度承認されたADRは変更せず、新しい決定が必要な場合は 新しいADRを作成して古いものを廃止する。