ドキュメントの負債は、技術的負債よりも早いペースで累積していく

エンジニアは技術的負債を本能的に理解しています。ショートカット（手抜き）が積み重なったコードベースでの作業がどのようなものか、彼らは身をもって知っています。当時はそれぞれ合理的だった判断も、それらが集まることで、あらゆる作業の難易度を跳ね上げます。彼らは、後から技術的負債を解消する方が、最初からそれを避けるよりもコストがかかることを知っており、あまりに長く放置すれば最終的には書き直しを余儀なくされることも理解しています。

ドキュメントの負債も全く同じように作用しますが、1つだけ重要な違いがあります。それは、誰も追跡していないため、より早く蓄積するということです。

技術的負債は、少なくともコードの中に部分的に可視化されています。乱雑なモジュールを読んでいる開発者は、その負債を感じ取ることができます。レビュアーがそれを指摘することもできます。リンターが一部を検出することもできます。一方、ドキュメントの負債は、不足しているドキュメントが必要になり、それが存在しないことに気づくまで目に見えません。その時点で遡ってドキュメントを作成するコストは、最初に作成しておくコストよりも遥かに高くなります。

どのように蓄積するか

対応するドキュメントの更新を行わずにリリースされるすべてのPRは、ドキュメントの負債をわずかに増やします。Slackのスレッドで決定され、恒久的な文書に記録されることのないすべてのアーキテクチャの決定も、負債をさらに増やします。優先順位が議論され、コンテキストが口頭で共有されたものの、決して書き留められることのないすべての会議も、負債をさらに蓄積させます。

個別に見れば、これらはどれも無視できるものに思えます。しかし、数ヶ月にわたって集積されると、システムが実際に何を行っているかと、最初の構築者以外の人間がシステムについて理解していることとの間にギャップが生じます。このギャップはスプリントごとに広がり、しかも目に見えない（指標で追跡されず、ダッシュボードにも表示されない）ため、ある引き金となる出来事によって痛烈に顕在化するまで、誰も気づかないうちに成長し続けます。

その引き金となる出来事は予測可能です。新入社員が生産性を発揮するまでに何ヶ月もかかること、主要なエンジニアが離職して重要なコンテキストを持ち去ってしまうこと、誰も影響を受けたシステムを十分に理解していないために原因特定が遅れ、障害対応が長引くこと、あるいは、1年前に決定され解決されたはずの議論をチームが再び蒸し返していることにアーキテクチャレビューで気づくことなどです。

なぜ技術的負債よりも早く複利で膨らむのか

技術的負債はコードの変更に伴って線形に蓄積します。1つのショートカットが1単位の負債を追加します。一方で、ドキュメントの負債は「複利」で増えていきます。なぜなら、ドキュメントの価値は「相関関係」にあるからです。サービスAに関するドキュメントは、サービスBやCに関するドキュメントと紐付いている時により有用になり、そのうちのどれか1つでも欠けていると、他のドキュメントの価値も低下してしまいます。

あるシステムのドキュメントが欠けていると、そのシステムと相互作用する他のシステムのドキュメントも、読者が繋がりを追えなくなるため有用性が下がります。ドキュメント化されていないシステムが増えるほど、個々のドキュメントが提供する価値は低下します。なぜなら、それらは繋がった全体像の一部としてではなく、孤立して存在することになるからです。

これは、ドキュメントの負債が単なる足し算ではないことを意味します。負債が少し増えるごとに、既存のドキュメントの価値が低下するため、負債の総コストは、新しい負債が追加されるペースよりも早く増加します。負債が顕著に感じられるほど大きくなった頃には、すでに大半のチームが投資したがる以上の解消コストがかかっており、そのため、多くの場合は課題に対処するのではなく、それを受け入れてその場しのぎでやり過ごすという対応が取られてしまいます。

チーム規模の転換点

ドキュメントの負債は、小規模なチームであれば許容できます。なぜなら、暗黙の知（属人化された知識）が代替案として機能するからです。チームが十分に小さいため、全員がすべてを知っています。転換点は通常、エンジニアが10人から20人の間で訪れます。これは多くのチームが急速に採用を始める時期でもあり、ドキュメントが最も必要とされるにもかかわらず、それを作成する時間が最も取れない時期でもあります。

このタイミングは不運ですが、予測可能です。チームが拡大し始める瞬間こそ、ドキュメントが不可欠になる瞬間であり、同時に既存のチームが最も手一杯になり、執筆という追加の作業をこなす余裕が最もなくなる瞬間でもあります。ドキュメントの重要性が低かった初期の段階に蓄積された負債が、突如として致命的なものとなり、その解消には、採用によって加速した機能開発（成長の原動力）からエンジニアリングの時間を割く必要が生じます。

この移行をうまく乗り切るチームは、通常、転換点の後ではなく前にドキュメントを自動化しているチームです。これにより、ドキュメントはチームの後を追うのではなく、チームとともに成長していきます。

よくある質問

ドキュメントの負債はどのように測定すればよいですか？ 代替指標を用います。新しいエンジニアが立ち上がるまでの期間、もし存在していれば解決したであろうSlackで尋ねられる質問の数、同じ決定事項が蒸し返される頻度、ドキュメントがあるシステムとないシステムでの本番障害の復旧時間（MTTR）などです。これらの中に直接ドキュメントの負債を測るものはありませんが、総合的にその規模を示してくれます。

ドキュメントのスプリントを設けるべきですか？ ドキュメントスプリントはバックログを解消しますが、継続的なドキュメント作成プロセス自体を変えなければ、負債はすぐにまた蓄積します。破産宣告をするようなものだと考えてください。一時は帳消しになりますが、支出の習慣は変わりません。構造的な解決策は、日々のエンジニアリング活動から自律的に生成されるドキュメントを導入することです。

どのチーム規模でこれが致命的になりますか？ ほとんどのチームはエンジニアが10〜20人の間でそれを実感し始めますが、負債自体は初日から蓄積され始めます。対処するのに最適なタイミングは、それを実感する前です。予防コストは、治療コストのほんの一部で済むからです。

関連する読み物: なぜエンジニアリングドキュメントが重要なのか、古いドキュメントはドキュメントがないよりも悪い、ドキュメントのパラドックス。 関連ページ: 自動で生成されるドキュメント、エンジニアリングチーム向け。