ドキュメンテーションのパラドックス：すべてのPRがドキュメントの正確性を低下させる

エンジニアリングドキュメントの根本的な問題は、それを書いた瞬間に、真実ではなくなり始める点にあります。

Wikiのページは、作成されたその日の決済サービスのアーキテクチャを正確に記述しています。しかし翌週、あるプルリクエスト（PR）によってリトライロジックが再構成されます。その次の週には、別のPRで新しい決済プロバイダーの連携が追加されます。1か月後、リファクタリングによって2つのモジュールが1つに統合されます。コードとドキュメントの間に関連性がないため、これらの変更のいずれもWikiページに更新を反映しません。PRが発生するたびにドキュメントの正確性はわずかに損なわれ、開発スピードが上がるにつれてその乖離は加速していきます。

これがドキュメントのパラドックスです。チームの開発スピードが上がれば上がるほど、ドキュメントが陳腐化するスピードも速くなります。つまり、信頼性の高いドキュメントを最も必要としているチームこそ、ドキュメントの劣化が最も早く進むチームなのです。手動でのドキュメント作成は、自らの開発スピードとの終わりなき競争であり、ドキュメントが常にコードの一歩後塵を拝している以上、決して勝つことのできないレースなのです。

なぜ手動メンテナンスは失敗するのか

ドキュメントの陳腐化に対する一般的な対策は、メンテナンスプロセスの構築です。責任者の割り当て、定期的な見直しサイクルのスケジュール、PRのチェックリストへのドキュメント更新の追加などです。これらのプロセスは一定の効果をもたらしますが、すべて人間の規律に依存しており、ドキュメントが最も重要となる状況下において、その規律はまさに崩壊しやすくなります。

チームが締め切りのプレッシャーの下で急速に開発を進めているとき、あるいはインシデントに対処しているとき、ドキュメントのメンテナンスは真っ先に後回しにされます。PRのレビュアーはドキュメントが更新されたかどうかのチェックを止め、Wikiページの管理者は見直しサイクルに遅れをとるようになります。メンテナンスプロセスは平穏なときには機能しますが、状況が逼迫しているときには機能しません。つまり、最も重要とされる瞬間に、最も機能しなくなるのです。

もう1つの問題は、特定のコード変更によってどのドキュメントが影響を受けるかを誰も把握していないことです。1回のリファクタリングによって、3つのWikiページ、2つのアーキテクチャ図、1つのオンボーディングガイドが無効になる可能性がありますが、変更を加えるエンジニアには、自分が修正しているコンポーネントをどのドキュメントが参照しているかを知る術がありません。ドキュメントを更新したいと考える良心的なエンジニアであっても、コードとドキュメントの紐付けが管理されておらず、往々にして存在すらしないため、確実に対応することは不可能なのです。

アーキテクチャによる解決策

目まぐるしく変化するコードベースに追随できる唯一のドキュメントは、コードを変更するのと同じソースから自律的に更新されるドキュメントだけです。

自己更新型（セルフライティング）ドキュメントは、実際のエンジニアリング活動からドキュメントを生成することで、このパラドックスを解消します。PRによって2つのサービス間の通信方法が変更されると、その通信に関するドキュメントは変更を反映して更新されます。Slackの会話で設計上の疑問が議論され解決されると、関連するドキュメントにその決定が組み込まれます。ミーティングで移行計画が扱われれば、ドキュメントには3か月前のものではなく、現在の計画が反映されます。

システムを変更するソースと同じ場所から作成されるため、ドキュメントは常に最新の状態に保たれます。ドキュメントはコードの活動から派生して作成され、コードと並行して手動で維持されるわけではないため、コードとドキュメントの間にギャップが生じることはありません。

エンジニアは生成されたドキュメントのレビューや推敲を依然として行いますが、基本的な正確性は自動的に維持されるため、レビューは「書き直し作業」ではなく「品質保証ステップ」へと変わります。ドキュメントを、動き続ける標的に手動で同期させ続ける必要がなくなるため、このパラドックスは解消されます。ドキュメントは標的とともに動くのです。

よくある質問

手動で維持されているドキュメントは、どのくらい早く陳腐化しますか？ 変化の激しいチームでは、ドキュメントが作成されてから数週間以内に重大な不正確さが生じることがあります。活発に開発が行われているコードベースにおいて、作成から3か月が経過したドキュメントは、大まかな方向性が合っていたとしても、詳細については通常信用できません。

ドキュメントに「最終確認日」を記載するだけで解決しませんか？ 読者にそのコンテンツをどれだけ信頼すべきかのシグナルを与えることができるため、何もないよりはマシです。しかし、根本的な問題は解決しません。依然として誰かがドキュメントを検証する必要があり、その検証には、どのコード変更がドキュメントを無効にした可能性があるかを理解する必要があるからです。

これはすべての種類のドキュメントに共通する問題ですか？ 実装の詳細、システムアーキテクチャ、および統合ポイントについて記述したドキュメントで最も深刻です。これらは最も頻繁に変更されるためです。一方で、概念的なドキュメント（なぜマイクロサービスを採用しているのか、テストに対する私たちの哲学など）は、根底にある決定が変わる頻度が低いため、より長持ちします。

関連する読み物：古いドキュメントはドキュメントがないよりも悪い、ドキュメント負債、自己更新型ドキュメントの解説。 関連ページ：自己更新型ドキュメント、エンジニアリングチーム向け。