Confluenceが機能しない理由（と、何が機能するのか）

エンジニアリングの分野で数年以上働いた経験があるなら、Confluenceのライフサイクルを経験したことがあるでしょう。新しいチームや新しいイニシアチブが、新しいConfluenceのスペースを作成します。モチベーションの高いエンジニアが、アーキテクチャの概要、設計ドキュメント、プロセスガイドなどの最初のドキュメントを作成します。最初の数週間、そのスペースは非常に素晴らしく見えます。

しかしその後、メンテナンスが滞るようになります。対応するドキュメントの更新が行われないままPRがリリースされます。アーキテクチャの変更も反映されません。新しいエンジニアが参画したとき、ドキュメントに記載されているのは6ヶ月前のシステムであることに気づきます。シニアエンジニアは新入社員に対して「Wikiはほとんど古くなっている」と警告し、読む代わりに直接誰かに尋ねるよう勧めます。Confluenceのスペースは、もはや存在しない現実のバージョンを記述した、構造化されて綺麗にフォーマットされたページという、善意の墓場と化してしまいます。

これはConfluence特有の問題ではありません。人間が手動でドキュメントを書き、メンテナンスすることに依存している、あらゆるドキュメントシステムに共通する問題です。NotionのWikiも同様に陳腐化します。Googleドキュメントも全く同じように乖離が蓄積していきます。GitBookのページも同じスピードで腐敗します。ツールが問題なのではありません。モデル自体が問題なのです。

手動ドキュメントが失敗する理由

手動のドキュメントが失敗するのは、直接的で目に見える価値を生まない作業を人間に要求するからであり、また、その取り組みが一回限りではなく継続的なものだからです。

ドキュメントを書くことは一回限りのコストです。しかし、それを最新の状態に維持することは無限のコミットメントです。毎回のスプリント、すべてのリファクタリング、すべてのアーキテクチャの変更がドキュメントのメンテナンス作業を生み出しますが、その作業は優先されることがありません。なぜなら、機能のリリースでも、バグ修正でもなく、誰かが追跡しているメトリクスを動かすものでもないからです。

その結果、強力なドキュメント文化を持つチームであっても、システムの変更スピードが常にドキュメントのメンテナンススピードを上回るため、着実にドキュメントの技術負債が蓄積していきます。リリースが速ければ速いほどドキュメントはすぐに陳腐化し、ドキュメントのパラドックスによって、ドキュメント化すべきものが最も多いチームほど、その作業に追いつけなくなります。

Confluenceの特定の設計は、いくつかの点でこの状況をさらに悪化させます。検索機能が弱いため、エンジニアはドキュメントが存在していても見つけられないことがよくあります。また、ページエディタがコードファイルの入力に比べて重いため、編集インターフェースが迅速な更新を妨げます。そしてその組織化は、誰かが積極的にスペース構造をメンテナンスすることに依存していますが、これもまた誰も優先しないメンテナンスの負担となります。

モデルの転換

代替案は、より優れたWikiツールではありません。ドキュメントがどのように作成されるかという、異なるモデルの導入です。

手動モデルでは、エンジニアが作業を行い、その作業について別のシステムに書き込みます。書くという行為は、最初の作業の上に重なる第二のタスクであり、時間的にもコンテキスト的にも切り離され、エンジニアのモチベーションに依存しています。

自己執筆モデル（セルフライティングモデル）では、ドキュメントは作業そのものから生成されます。PR（プルリクエスト）の説明がシステム変更ドキュメントになり、Slackでの会話が意思決定の記録になります。ミーティングの議論が計画やアーキテクチャのドキュメントになります。エンジニアはドキュメントを書きません。システムがエンジニアの既存のアウトプットから自動的に書き上げるのです。

この転換が重要なのは、手動ドキュメントを台無しにする2つの失敗パターンを排除できるからです。それは、モチベーションの問題（エンジニアはドキュメントを書きたがらない）と、最新性の問題（メンテナンスが優先されないためドキュメントが古くなる）です。

自己執筆型Wikiとはどのようなものか

自己執筆型エンジニアリングWikiとは、連携された情報源から自動的にメンテナンスされる、構造化され検索可能なナレッジベースのことです。

システムドキュメントはPRがマージされると更新され、誰かが最後にWikiページの更新を覚えている時点の状態ではなく、各システムの現在の状態を反映します。

意思決定レコード（ADR）は、アーキテクチャの選択が議論され解決されたSlackのやり取りから作成され、決定事項とその理由を一緒に保存します。

オンボーディング資料は、最後に誰かが採用した際に更新を促されたときのスナップショットではなく、現在のシステムを記述しているのと同じソースから派生しているため、常に最新の状態が保たれます。

変更履歴はPRや会話から編集され、各システムがどのように進化してきたか、そしてその理由のタイムラインを提供します。

ドキュメント内のすべての主張はそのソースにリンクバックしているため、エンジニアは元のPR、メッセージ、または会議の書き起こしをクリックするだけで、何でも検証できます。この引用アーキテクチャこそが、自己執筆型ドキュメントとAIが生成したテキストを区別するものです。つまり、ドキュメントが推論に基づくものではなく、エビデンス（証拠）に基づいているということです。

移行プロセス

Confluenceから自己執筆型Wikiへの移行において、初日にすべての既存コンテンツを移行する必要はありません。現実的なアプローチは以下の通りです。

エンジニアリングのソース（GitHub、Slack、ミーティング）を連携します。システムが現在の活動からドキュメントの生成を開始できるようにします。今後は新しいドキュメントの作成に自己執筆型Wikiを使用します。既存のConfluenceスペースは、歴史的な参照用レガシーアーカイブとして残しておき、自己執筆型Wikiがチームの主要なリファレンスになるにつれて、自然に役目を終えさせます。

数週間もすれば、自己執筆型Wikiにはライブのアクティビティから生成された最新のドキュメントが蓄積され、一方でConfluenceスペースには関連性の薄れつつある過去のドキュメントが残ることになります。エンジニアは信頼できるソースに自然と引き寄せられ、自動的に最新が保たれるソースは、手動でのメンテナンスが必要なソースよりも早く信頼を獲得するため、この移行は有機的に発生します。

よくある質問

Confluenceのセットアップに多くの投資をしてきました。完全に捨てる必要がありますか？ いいえ。自己執筆型Wikiは、今後の新しいドキュメント作成に対応します。既存のConfluenceコンテンツは、歴史的な参照用としてアクセス可能な状態のまま維持されます。時間が経つにつれて、エンジニアは自然とより最新で信頼できるソースをデフォルトにするようになりますが、強制的な移行を行う必要はありません。

出力の品質は、よく書かれた手動のドキュメントと同等ですか？ 事実に関するドキュメント（システムが何を行うか、どのように変更されたか、何が決定されたか）については、手動のドキュメントが選択的に記録するのに対し、自動化システムは包括的に記録するため、品質は同等かそれ以上です。ナラティブ（語り口）を伴うドキュメント（アーキテクチャの哲学、設計原則、チーム文化）については、やはり人間が書く方が優れています。最善の結果は、事実に基づいたドキュメントを自動でカバーし、その上に人間が書いたナラティブドキュメントを重ねることです。

情報の競合はどのように処理されますか？ システムは、競合を解決するためにソースの新しさと権限を使用します。昨日マージされたPRは、3ヶ月前のSlackメッセージよりも優先されます。システムが自動的に解決できない競合が発生した場合は、人間がレビューできるようにフラグが立てられます。

関連する読み物: 自己執筆型ドキュメントの解説、ドキュメントのパラドックス、エンジニアがドキュメント作成を嫌う理由。 関連ページ: 自己執筆型ドキュメント、エンジニアリングチーム向け、FabricとConfluenceの比較。