Documentation Rot：エンジニアリングWikiが6ヶ月で死ぬ理由
エンジニアリングWikiは急速に劣化します。このフォレンジックタイムラインがdocumentation rotの発生過程と、実際に防止できるシステムを示します。
By Ellis Keane · 2026-04-07
すべてのエンジニアリングチームには、Notionワークスペース（またはConfluenceインスタンス、またはGitHub wiki、またはチームが設立された年に流行していたドキュメントツール）があり、「Service Architecture Overview」のような名前のページがあります – 11ヶ月前にもう退職した誰かが最後に編集したものです。そのページはドキュメントではなく化石であり、それを化石に変えたdocumentation rotは書かれた翌日に始まりました – それはおおよそ全員が「これを最新に保つことが本当に重要だ」と合意した同じ日です。
Wikiページは凍結されたまま、周囲のすべてが動き続けます。誰も削除しません – 削除は破壊的に感じるから。誰も更新しません – 更新は他の誰かの仕事に感じるから。それはただそこに在り続け、権威あるように見えながら、ゆっくりとフィクションになっていきます。 attribution: Ellis Keane
私たちはdocumentation rotを規律の問題として扱いがちです – エンジニアがページを最新に保つことにもっと関心を持てばよいだけだ、本当のボトルネックはアーキテクチャではなくモチベーションだ、というように。しかし、私たちが話を聞いたチーム全体でこのパターンが繰り返されるのを見てきた結果（そして正直なところ、私たち自身の小さなオペレーション内でも – 私たちもこれに無縁ではありません）、失敗は常に同じです：ドキュメントはある場所に存在し、コード変更は別の場所で起こり、それらを結びつけるシステムがない。関心の問題ではありません。ドキュメントの仕組みとエンジニアリング作業の実際の流れとの間の根本的な不一致の問題であり、その不一致に対するプロセスだけの解決策はまだ見つかっていません – 試し続けてはいますが。
Wikiページのフォレンジックタイムライン
以下はエンジニアリングチームとの会話から（そして残念ながら私たち自身の経験から）引き出した複合的な記録ですが、この流れは組織をまたいで非常に一貫しているため、具体的な詳細はほとんど問題になりません。社内ドキュメントの一つに実際に起こること – 作成された瞬間から、誰かがそれを信頼して誤った判断を下す瞬間まで – を見ていきましょう。
title: "あるWikiページが危険になるまで" 1日目|ok|エンジニアが大規模リファクタリング後に「Payment Service Architecture」を作成。正確で詳細、シーケンス図を含む。 14日目|ok|2人の開発者がオンボーディング中にこのページを参照。数時間を節約。ページは成功に見える。 31日目|amber|チームメイトがpayment serviceのリトライロジックをリファクタリング。PRがマージされる。誰もWikiページのことを考えない。 45日目|amber|チームが共有Postgresインスタンスから専用インスタンスに移行。Wikiページのデータベース接続セクションは、もう存在しないインフラを記述している。 72日目|amber|新しいエンジニアがページを読み、記述されたデータベース設定に基づいてローカル環境をセットアップ。動かない。同僚が「ああ、そのページは古いよ」と言うまで午後いっぱいデバッグに費やす。 90日目|missed|午前2時にインシデントが発生。オンコールエンジニアがサービスのエスカレーションパスを確認するためにWikiページを参照。記載されたオーナーは2ヶ月前に退職済み。正しい担当者を見つけるのに20分を失う。 180日目|missed|ページは6ヶ月間で数十回閲覧された。1日目以降の編集回数はゼロ。すべてのセクションに少なくとも1つの不正確な記述がある。どの部分がまだ正しいのか誰も知らない。
5人以上のエンジニアがいるチームで働いたことがあるなら、おそらくこのタイムラインの何らかのバージョンを経験しているでしょう。今「うちにはそのためのプロセスがある」と首を振っているなら、自分のWikiの最終更新日を確認してみることをお勧めします。具体的な違いはあるでしょう（アーキテクチャドキュメントではなくAPIリファレンスかもしれない、NotionではなくConfluenceかもしれない、インシデントは午前2時ではなく3時だったかもしれない） – しかし、劣化曲線は常に、頑固に、同じです。
「ドキュメントを更新すればいい」がうまくいかない理由
Documentation rotへの最も一般的な対応はプロセスです：「PRチェックリストの一部としてドキュメントを更新すべきだ。」合理的に聞こえます。私たちの経験では、失敗することの方が多い – インセンティブ構造を辿れば明白な理由でです。エンジニアが一日の終わりまでに（そして一日の終わりは誰の予想よりも早く到来するものです）変更のレビュー、マージ、デプロイを終わらせようとしているとき、変更したコンポーネントに間接的に言及しているドキュメントページは、よくて頭の片隅にある漠然とした意識、最悪の場合は存在自体を知らないものです。CIパイプラインがグリーンになり、PRがマージされ、誰のワークフローにも「古い動作を暗黙的に前提としているすべてのWikiページを見つける」というステップは含まれていません。
そして誰もが口に出したがらない部分がこれです：たとえそのページを覚えていたとしても、具体的に何を変更すべきかわからないことが多い。コード変更とそのドキュメントへの影響の関係は、常に明白とは限りません。リファクタリングされた関数シグネチャは3つの異なるWikiページを無効にするかもしれませんが、それらのどのページもその関数を名前では言及していません。
Documentation rotは怠慢が原因ではありません。コード変更とドキュメント変更がまったく異なるツールで、まったく異なるタイミングで、まったく異なるインセンティブ構造のもとで行われるという事実が原因です。両者のつながりは完全に人間の記憶で維持されており、人間の記憶は間接的な依存関係を追跡するための信頼できるシステムではありません。
Documentation Rotの3つの段階
ドキュメントは一夜にして正確なものから危険なものに変わるわけではありません – それこそがこれほど陰険な理由です。3つの明確な段階を経て進行し、各段階は前の段階よりも検出が難しく、「このページは今、人々に嘘をついています」という通知を受け取る時点はありません。
第1段階は表面的な漂流で、数週間以内に始まります。変数名が変わり、URLパスが更新され、「オーナー」フィールドのチームメンバーの名前が組織再編後に間違いになる。核心的な情報はまだ方向性としては正しく、詳細がずれていてもページを読んだ人は正しい概要を得られます。まだ何も壊れたようには感じられません（この時点ではほとんどそう感じることはありません）ので、誰も何も直しません – 表面的に漂流したWikiページを直すのは、エンジニアリング版のフロスの使用に相当するからです：誰もが重要だと同意しますが、今日やる人はいません。
次に構造的な乖離が来ます – 通常1ヶ月から3ヶ月頃 – アーキテクチャ自体がページの記述を超えて進化しています。サービスが2つに分割されたかもしれない、エンドポイントが廃止されまったく異なるコントラクトのものに置き換えられたかもしれない、認証フローが完全に変更されたかもしれない。この段階では、ページは積極的に誤解を招いていますが、それでも権威ある見た目をしています（図がある、見出しがある、明らかに何を話しているか知っている人が書いたもの） – そのため読者は必要以上に長くそれを信頼する傾向があります。それが本当に危険な部分です。
3ヶ月から6ヶ月頃には、危険なフィクションに到達しています。ページは存在しないシステムを記述しています。記載されたエンドポイントは404を返します。データベーススキーマは2回マイグレーションされています。エスカレーションパスが示す人物は、この時点では別の会社で働いていて、おそらくそのサービスが存在したことすら忘れています。
stat: "編集ゼロ回" headline: "6ヶ月間で" source: "エンジニアリングWiki全体で観察されたパターン"
この段階でのdocumentation rotによる被害は理論上のものではありません。エンジニアはデプロイ判断、インシデント対応判断、オンボーディング判断を – 率直に言えば – フォーマットされたフィクションであるドキュメントに基づいて行っています。
実際に劣化を遅らせるもの
プロセスチェックリストが機能しないなら（上記の構造的な理由により機能しません）、何が機能するのでしょうか？正直な答えは、documentation rotを完全に排除するものはないということですが、一部のチームはWikiページの半減期を数週間から数ヶ月に延ばせるほどに遅らせることに成功しています – これは「たまに誤解を招く」と「積極的に危険」の違いです。私たちが話を聞いた中で最も良い結果を出しているチームには、いくつかの共通パターンがあります。
コードの近くに存在するドキュメント。 リポジトリ内のREADME、インラインコメント、記述するコードと一緒にコミットされるアーキテクチャデシジョンレコード（ADR）。これらには自然な利点があります：コードが変更されると、ドキュメントはまさにそこにあり、同じdiffの中でエンジニアの目に入ります。更新が保証されるわけではありませんが（何事も保証はありません）、近接性だけで更新される可能性が大幅に高まります。
自動化された陳腐化検出。 一部のチームは、90日間編集されていないWikiページにフラグを立てるシンプルなスクリプトを実行しています。粗いアプローチですが、第3段階に達する前に問題を表面化させます。メカニズムよりも原則が重要です：ドキュメントの正確性を、ただ祈るのではなく、測定できるものとして扱うこと。
より少なく、より短いドキュメント。 3,000語のアーキテクチャ概要は、特定のコンポーネントに焦点を当てた500語のページ3つよりも速く劣化します。表面積が小さいということは、各ページで問題が起こりうる要素が少ないということであり、最新に保つ責任者がページ全体を実際に頭の中に保持できるということです。
劣化を遅らせるもの
- コード隣接ドキュメント – リポジトリ内のREADMEとADR、同じPRで更新
- 陳腐化アラート – 90日間未編集のページへの自動フラグ
- 小さく焦点を絞ったページ – 劣化が付け入る表面積が少ない
効果がないもの
- PRチェックリスト – 「ドキュメントを更新」というチェックボックスが行動なしにチェックされる
- ドキュメントスプリント – 1週間の更新が1ヶ月以内に劣化する
より深い問題：ドキュメントはスナップショット、作業はストリーム
上記のすべての修正は緩和策であり、それについて正直であるべきです。根本的な問題は、ドキュメントはその性質上、継続的に変化するものの時点スナップショットであるということ – そしてどれだけプロセスを重ねてもその根本的な緊張は変わらないということです。今日のシステムの姿を書き留め、明日にはシステムが変わり、ドキュメントはすでに劣化し始めており、誰かが痛い目に遭うまで誰も気づきません。
この問題に最も悩まされないチーム（そして「最も」がどのようなものか、正直なところまだ模索中です – 誰もこれを本当に解決していないので）は、静的なドキュメントから生きた、クエリ可能なコンテキストへと移行したチームです。「payment serviceはプラットフォームチームが担当」と書き留める代わりに、実際のコミット、PR、そして本当の意思決定が行われたSlackスレッドを見ることで「最近payment serviceに取り組んでいるのは誰か？」という質問に答えられるツールを持っています。
具体的には、CODEOWNERSと最近のコミット著者から導出されるオーナーシップ、CIから取得されるデプロイ履歴、ページャーログから検索されるインシデント対応者、そしてリンクされたLinear issueとSlackスレッドを通じて追跡される意思決定コンテキストを意味します。それはWikiではなく、伝統的な意味でのナレッジマネジメントでもありません。人々がすでに使っているツールから取得するため最新であり続ける – 不可避に、予測通りに劣化する別のアーティファクトの維持を求めるのではない – 生きたインデックスです。
最も信頼できるドキュメントは、誰も書く必要がない種類のものです。コンテキストが実際に作業が行われるツール（コードリポジトリ、イシュートラッカー、コミュニケーションチャネル）から取得されるとき、それははるかにゆっくりと劣化します – 誰かが書き留めることを覚えていたものではなく、実際に起きていることを反映しているからです。
従来型ドキュメントが本当に必要な場合
上記のいずれも、Wikiが無用であることを意味しません。人間によって書かれ、意図的に維持され、散文として保存されることが真に有益なドキュメントの特定のカテゴリがあります：
- オンボーディングガイド – アーキテクチャ上の意思決定の背後にある「なぜ」を説明するもの、単に「何」だけではなく
- ランブック – インシデント対応用、読者は午前2時にチェックリストを必要とするストレスを抱えたエンジニア、ナレッジグラフクエリではなく
- コンプライアンスドキュメント – 構造化されバージョン管理されたアーティファクトを期待する監査人が要求するもの
- パブリックAPIリファレンス – 外部開発者が利用するもの
重要な区別：これらのドキュメントはゆっくり変化するもの（企業の価値観、コンプライアンス要件、パブリック契約）、または現在の正確性よりも叙述的コンテキストが重要なもの（3年前になぜPostgresをDynamoDBより選んだか）を記述しています。
それ以外のすべて（誰が何を所有しているか、現在のアーキテクチャは何か、その意思決定はどこでなされたか）について、答えは誰かが6ヶ月前に書いたWikiページであるべきではありません。実際に何が起きたかに対するクエリであるべきです。
シグナルインテリジェンスを受信トレイにお届けします。
よくある質問
Q: エンジニアリングチームにおけるdocumentation rotとは何ですか？ A: Documentation rotとは、社内ドキュメントの正確性が時間とともに徐々に劣化していく現象です。書かれた時点では正確だったページが、コード、プロセス、チーム構成がその周囲で変化するにつれて、誤解を招くものになります。ドキュメント自体は凍結されたまま、それが記述しているすべてが進化し続けます。
Q: Sugarbugはdocumentation rotの防止に役立ちますか？ A: SugarbugはGitHub、Linear、Slack、NotionなどのツールにAPI経由で接続し、ワークフロー全体で実際に起きたことのナレッジグラフを構築します。手動で維持するWikiページに頼る代わりに、チームは実際の活動から本物のコンテキストを引き出すことができ、ツール自体から取得されるため正確性が保たれます。
Q: エンジニアリングドキュメントはどのくらい早く古くなりますか？ A: 私たちの経験とエンジニアリングチームとの会話から、Wikiページは作成後数週間以内に現実との乖離が始まることが多いです。6ヶ月後には、多くのページが記述された形式ではもはや存在しないプロセス、エンドポイント、またはオーナーシップ構造を記述しています。
Q: エンジニアリングドキュメントを最新に保つ最良の方法は何ですか？ A: 最も効果的なアプローチは、コード隣接ドキュメント（リポジトリ内のREADMEとADR）、自動化された陳腐化アラート、そして手動で維持するページに頼る代わりに実際のツールからコンテキストを取得する生きたクエリへの移行です。プロセスチェックリスト（「すべてのPRでドキュメントを更新」）は、インセンティブ構造がそれを支えていないため、一貫して失敗します。