ブログ
誰もドキュメントを読まない(そしてそれは彼らのせいではない)

社内ドキュメントやWikiを維持しようとしたことのあるすべての企業が、同じライフサイクルを経験しています。熱狂的な立ち上げ、最初のコンテンツ作成、貢献の緩やかな減少、忍び寄る陳腐化、信頼の低下、そして機能的な放棄。Wikiは依然として存在します。検索結果にも表示されます。しかし、誰もそれを信頼していません。なぜなら、最後に誰かがWikiページの指示に従ったとき、その指示は3ヶ月も前の古いものであり、結果として午後の時間が無駄になったからです。
Wikiが失敗する標準的な説明は文化的なものです。人々が怠惰である、誰もドキュメントを重視していない、エンジニアに書かせるのが難しい、といった理由です。この説明は間違っており、間違った介入(執筆の義務化、ドキュメントスプリント、貢献のゲーム化)を招くことになります。これらは一時的な遵守を生むだけで、永続的な変化をもたらしません。
Wikiが失敗するのは構造的な理由によるものであり、それぞれの失敗パターンには構造的な解決策があります。
失敗パターン1:陳腐化
ドキュメントは書かれた瞬間に陳腐化し始めます。なぜなら、記述されているシステムは変化し続ける一方で、Wikiは固定されたままだからです。マージされたPR、アーキテクチャの変更、プロセスの調整のすべてが、Wikiの正確性を少しずつ損なっていきます。誰も更新の責任を負っておらず、仮に責任者がいたとしても、どの変更がどのページに影響を与えるかを体系的に知る方法はありません。
解決策: 実際の活動から自己更新するドキュメント。WikiがGitHubのPR、Slackでのディスカッション、そして会議の録音から生成されるようになれば、基礎となるシステムを変更するのと同じソースから派生するため、常に最新の状態が保たれます。
失敗パターン2:貧弱な検索
ほとんどのWikiツールはキーワードで検索するため、何かを見つけるには著者が使用した正確な言葉を推測する必要があります。「認証フロー」では「ログインアーキテクチャ」が見つかりません。「デプロイガイド」では「リリース手順書」が見つかりません。2〜3回検索に失敗すると、ユーザーは情報は存在しないと判断し、代わりに人に尋ねるようになります。
解決策: 意味からコンテンツを見つけるセマンティック検索。探しているものを説明すれば、使用されている具体的な言葉に関係なく、システムが概念的に関連する結果を見つけ出します。
失敗パターン3:貢献者に依存する整理
各貢献者はページの構成を異ならせ、独自のルールに従って名前を付け、その時点で妥当と思われる場所にファイルを保存します。その結果として生じる情報アーキテクチャは、何かを探そうとしている人のニーズではなく、20人の異なる人々の組織的な習慣を反映したものになります。
解決策: 自動的に生成される一貫した構造。自動執筆ドキュメントは、誰が基礎となる活動を生成したかに関係なく、標準的な形式(システム概要、決定記録、変更ログ)に従います。整理は個々の貢献者ではなく、システムによって決定されます。
失敗パターン4:貢献のオーバーヘッド
Wikiページを作成することは、そのページが説明する作業を行うこととは別の活動です。作業から執筆へのコンテキストの切り替え、何を含めるべきかの判断、そしてそのページを無期限に維持し続ける必要があるという認識が求められます。このオーバーヘッドは、時間が逼迫している状況では常に後回しにされます。
解決策: 自動的に行われる貢献。ドキュメントが作業自体(Slackでの会話、PRの説明、会議での議論)から生成される場合、貢献は追加のタスクとしてではなく、作業の副産物として発生します。誰もWikiを書きません。Wikiが自らを書くのです。
機能しているWikiの姿
人々が実際に読み、信頼するWikiには4つの特性があります。最新であること(自動更新)、見つけやすいこと(セマンティック検索)、一貫していること(標準化された形式)、そして低労力であること(手動での貢献が不要)です。従来のWikiのほとんどはこれらの特性を1つも備えていないため、誰にも読まれないのです。
セマンティック検索を備えた自動執筆ドキュメントは、これら4つすべてを提供します。その結果、陳腐化や貧弱な検索によって信頼を失うのではなく、正確性と有用性によって信頼を獲得するナレッジベースが生まれます。人々は、読むように指示されたからではなく、役に立つから読むのです。
よくある質問
既存のWikiは削除すべきですか? 歴史的なアーカイブとして残しておき、それと並行して新しい自動執筆Wikiを構築してください。時間が経つにつれて、人々は自分が信頼するソース(最新で検索可能なもの)に引き寄せられ、古いWikiは主要なナレッジベースではなく、レガシーな参照先となるでしょう。
人の手で書く必要があるページ(スタイルガイド、ポリシーなど)はどうすればよいですか? 企業のポリシー、ブランドガイドライン、哲学的なドキュメントなど、一部のコンテンツは人間の手による執筆を必要とします。これらは自動生成されたドキュメントと並行して存在します。自動執筆システムは事実に基づいた運用のドキュメントを扱い、人間はストーリーや規定に関するコンテンツを扱います。
チームに新しいWikiを信頼してもらうにはどうすればよいですか? 信頼は正確性によって築かれます。Wikiを5回検索して、5回とも有用で最新の結果が得られれば、人々は検索し続けるでしょう。従来のWikiにおける信頼の問題は、時間の経過とともに正確性が低下することです。自動執筆ドキュメントは正確性を自動的に維持するため、信頼も維持されます。
関連資料:ナレッジベースとは、古いドキュメントはドキュメントがないよりも悪い、Confluenceが機能しない理由。関連ページ:自動執筆ドキュメント、検索、何でも見つける。
その他のブログ記事:

Agent memory vs a shared drive

Can AI agents use Google Drive or Dropbox?

What happens when an AI agent deletes the wrong file

Why AI agents give up searching your files

Why AI agent access should expire

Your agent instruction files are a security risk

When two AI agents edit the same file

Ask your files, don't build a dashboard