古いドキュメントは、ドキュメントがないことよりも厄介です。

ドキュメントがまったく存在しないチームは、ドキュメントがないことを自覚しています。エンジニアは質問し、同僚に声をかけ、口頭でコンテキストを再構築します。非効率的ではありますが、少なくとも全員がその状況を理解しています。

古いドキュメントを抱えるチームは、これとは異なる問題を抱えています。ドキュメントは存在し、いかにも信頼できそうに見えますが、内容は間違っています。エンジニアはセットアップガイドに従いますが、3ヶ月前に変更された依存関係をガイドが参照しているために、午後の時間を丸々無駄にしてしまいます。別のエンジニアはアーキテクチャの概要を読み、それに基づいて設計を決定しますが、コードレビューの段階になって、その概要が前四半期に再構築されたシステムのものであることに気づきます。

このような経験を2、3回繰り返すと、エンジニアはドキュメントを信用しなくなります。そして、直接人に尋ねるという、ドキュメントが最初から存在しなかった場合と同じ行動に戻ります。しかし今やチームは、ドキュメントが解消するはずだった「口頭での知識共有」のコストに加え、誰も読まないドキュメントを「維持する」コストまで支払うことになります。

これこそが、最も有害な形での「ドキュメントのパラドックス」です。ドキュメントへの投資が、単に存在しない場合よりも、積極的に誤った方向へ導いてしまうために、マイナスのリターンを生み出しているのです。

ドキュメントが陳腐化する理由

ドキュメントが風化するのは、エンジニアが怠慢だからではありません。PR（プルリクエスト）がマージされるたびに既存のドキュメントの正確性がわずかに損なわれ、その修正作業が優先されることがないためです。

リファクタリングによって、2つのサービス間の通信方法が変わるとします。エンジニアはコードを更新し、テストを書き、PRのレビューを受けてマージします。しかし、古い通信パターンを説明している3つのWikiページを更新することは、PRのチェックリストにも、スプリントのタスクにも含まれていません。どのコード変更がどのドキュメントに影響を与えるかを誰も追跡していないため、誰もそのタスクを割り当てません。Wikiページはそこに放置され、もはや存在しないシステムを説明し続け、誰かがそれに従って失敗するのを待つことになります。

陳腐化のスピードは、デプロイ（リリース）の速度に直接比例します。開発のスピードが速ければ速いほど、ドキュメントはすぐに古くなります。つまり、信頼性の高いドキュメントを最も必要としているチーム（動きが速く、急速に進化するコードベースを持つチーム）こそが、ドキュメントが最も早く風化するチームなのです。

信頼の問題

ドキュメントに対する信頼は、一度失われると再構築するのが極めて困難です。最初にドキュメントを確認する習慣を身につけるには、正確で役立つドキュメントに何十回も目を通す必要があります。しかし、その習慣を壊すには、1、2回の誤解を招く体験だけで十分なのです。

開発チーム全体が「ドキュメントは信用できない」と学習してしまうと、ドキュメントは存在しないも同然になります。新入社員は口頭で「Wikiはほとんど古いから、読むより直接聞いたほうがいい」と教えられます。ドキュメントは依然として存在し、検索結果にも表示され、公式なものに見えますが、実質的には放棄されています。それを書くために費やされたすべての時間が無駄になってしまうのです。

この問題を回避できる唯一のドキュメントは、自動的に最新状態に維持されるドキュメントです。実際の開発活動（PR、Slackのスレッド、会議の録画）から生成される自己記述型（自動作成）ドキュメントは、基となる活動の変化に合わせて更新されます。ドキュメントは現実と並行して手動で維持されるのではなく、現実から作成されるため、常に実態を反映します。

監査の問い

あなたのドキュメントがこの問題を抱えているかどうかを診断する簡単なテストがあります。最後に更新されたのが3ヶ月以上前の、ランダムなWikiページやアーキテクチャドキュメントを1つ選んで読んでみてください。そして、そのシステムを現在担当しているエンジニアに、そのドキュメントが今でも正確かどうか尋ねてみてください。

ほとんどのチームでは、その回答は「一部は合っているけれど、詳細がいくつか変わっている」というようなものになるでしょう。そして、その「変わってしまった詳細」こそが、次のエンジニアの午後の時間を無駄にする原因なのです。

よくある質問

古いドキュメントは単に削除すべきですか？ 明らかに古いドキュメントは、放置して人々を誤誘導するくらいなら削除したほうがマシです。しかし、より良い解決策は、後から片付けることではなく、陳腐化自体を防ぐことです。ライブソースから自動作成されるドキュメントは、基となる活動の変化に合わせて更新されるため、同様に陳腐化することはありません。

どのドキュメントが古いか、どうすれば分かりますか？ ドキュメントが最後に更新された日時を、そこに記載されているシステムが最後に変更された日時と比較して追跡します。たとえば、認証フローに関するドキュメントが最後に編集されたのが1月で、それ以降に認証サービスに40個のPRがあった場合、そのドキュメントはほぼ確実に古くなっています。

開発スピードが速い場合、手動でドキュメントを維持する価値はありますか？ 開発スピードが速ければ速いほど、手動のドキュメントは急速に風化します。つまり、開発スピードが上がるにつれて、手動ドキュメントの投資対効果（ROI）は低下します。スピード感のあるチームにとっては、自動化されたドキュメント作成こそが、そのスピードに追従できる唯一のアプローチです。

関連する読み物: ドキュメントのパラドックス、ドキュメントの負債、エンジニアがドキュメント作成を嫌う理由。関連ページ: 自己記述型ドキュメント、エンジニアリングチーム向け。