ドキュメント管理

技術ドキュメントは、コードと同様にシステムの一部として継続的に管理される必要がある。「なぜその設計を選んだのか」という文脈はコードから読み取ることができず、ドキュメントにしか残らない。ADR（Architecture Decision Record）は、特定の設計判断とその背景・代替案・トレードオフを記録する軽量なフォーマットであり、将来の変更者が同じ議論を繰り返さないようにする効果がある。

Docs as Codeは、ドキュメントをソースコードと同じGitリポジトリで管理し、プルリクエストレビューや自動テストの対象とするアプローチである。Markdownファイルとしてドキュメントを保存することで、変更履歴が追跡できるようになり、コードの変更とドキュメントの変更を同時にレビューできる。これによりドキュメントの腐敗（Documentation Rot）—コードが変わってもドキュメントが更新されない状態—を防ぐ仕組みを作りやすくなる。

OpenAPI / Swaggerによるコードからの自動生成は、API仕様書を常に実装と一致させるための実用的な手段である。手書きのドキュメントは実装との乖離が生じやすいが、アノテーションやスキーマ定義から自動生成することで、開発者がドキュメントの同期を意識せずとも最新状態を保てる。READMEには最低限、プロジェクトの目的・セットアップ手順・基本的な使い方・コントリビューション方法を含めることが標準的な要件となる。

コードレビューで着目するポイント

新しい設計判断（技術選定・アーキテクチャ変更）にADRが作成されているか
READMEのセットアップ手順が実際に動作するか（新規メンバーが手順通りに実行できるか）
publicなAPIやライブラリのインターフェースにドキュメントコメントが付いているか
OpenAPI / GraphQLスキーマがコードから自動生成される仕組みになっているか
ドキュメントがコードの変更に追従しているか（古い情報が残っていないか）
内部向けドキュメントと外部向けドキュメントが適切に分離されているか
ドキュメントにサンプルコードがある場合、そのサンプルが実際に動作するか確認されているか

典型的なアンチパターン

ドキュメントの腐敗: コードのリファクタリング時にドキュメントが更新されず、READMEのセットアップ手順が3ヶ月前の状態のまま残る。新規メンバーが手順通りに実行してもエラーになり、口頭でしか知識が伝わらない状態になる。CI/CDでドキュメントのサンプルコードをテストするなどの仕組みで防ぐ。

「なぜ」がないADR: 「AWSを選択した」という事実だけを記録し、なぜGCPではなくAWSを選んだのか、どんな代替案を検討したのかが書かれていないADR。将来の変更時に同じ検討を一から行う羽目になる。

すべてをWikiに書く: コードと分離したWikiページにドキュメントをまとめると、コードが変わってもWikiは誰も更新せず、必然的に情報が陳腐化する。Docs as Codeの原則に従い、ドキュメントはコードと同じリポジトリに置くべき。

参考リソース

ADR GitHub Organization (https://adr.github.io/) — ADRフォーマットの定義とツール一覧
OpenAPI Specification (https://spec.openapis.org/) — RESTful API仕様記述の業界標準
Diátaxis Framework (https://diataxis.fr/) — チュートリアル・ガイド・リファレンス・説明の4分類でドキュメントを整理するフレームワーク
Redoc / Swagger UI — OpenAPIファイルからインタラクティブなAPIドキュメントを生成するツール
Docs for Developers (Bhatti et al.) — 技術ドキュメントの書き方と維持に特化した実践書