不適切なドキュメントは、実際にどれほどのコストをもたらしているでしょうか？

質の悪いドキュメントは、一見しただけでは見えないコストの1つです。「情報が明文化されていないために無駄になった時間」という予算項目は存在しません。「誰も元の議論をドキュメント化しなかったために、蒸し返された決定事項」を追跡している人はいません。「システムがなぜこのように構築されたのかを理解していなかったエンジニアによって引き起こされたバグ」を測定している人もいません。しかし、これらはすべて実質的なコストであり、中規模のエンジニアリングチームであってもこれらを合計すると、対策を講じる価値があるほど大きな金額になります。

以下に、あなたのチームの数値を算出する方法をご紹介します。

カテゴリー1：シニアエンジニアへの割り込み

同僚が口頭で回答する質問はすべて、本来エンジニアリング作業に充てられたはずの時間です。そのコストは、割り込みそのものと、そこからの復帰時間（1回の割り込みにつき約25分間の集中力の喪失）の合計になります。

入力項目：

• シニアエンジニアの人数

• ドキュメントがあれば解決できたはずの質問による、1日あたりの想定割り込み回数（通常は3〜8回）

• 1回の割り込みあたりの平均復帰コスト：25分

• シニアエンジニアの総人件費（時間給換算）

計算例： シニアエンジニア5人 × 1日5回の割り込み × 25分 × 時給95ドル × 年間労働日数250日 = 年間 248,000ドル

1回1回の割り込みは些細なことに感じられるため、ほとんどのチームは割り込み回数を過小評価しています。1週間追跡してみると、通常は想定よりも高い数値になります。

カテゴリー2：オンボーディングの遅れ

優れたドキュメントがあれば短縮できたはずの、新入社員が立ち上がりに費やす時間。その長引いた週数分だけ、生産性が低い状態に対して給与が支払われていることになります。

入力項目：

• 年間エンジニア採用数

• 現在のドキュメントでの、想定立ち上がり期間（週数）

• 優れたドキュメントがある場合の、想定立ち上がり期間（週数、通常は40〜60%短縮）

• 新入社員1人あたりの月間総人件費

計算例： 年間採用8人 × 短縮可能な立ち上がり期間4週間 × 週あたりの総人件費4,500ドル = 年間 144,000ドル

カテゴリー3：決定事項の蒸し返し

過去の決定事項がドキュメント化されていないと、チームはすでに解決されたはずの疑問を議論するために会議の時間を費やすことになります。そのコストは、会議の時間に参加者数を掛けたものになります。

入力項目：

• 過去の決定事項を蒸し返す会議に費やした、1か月あたりの想定時間（時間数）

• それらの会議の平均参加者数

• 平均総人件費（時間給換算）

計算例： 1か月あたり4時間 × 参加者5人 × 時給85ドル × 12か月 = 年間 20,400ドル

一見小さく見えますが、間接的なコストはさらに大きくなります。蒸し返された決定事項は、それに依存する作業を遅らせ、その遅れはスプリント全体に連鎖します。

カテゴリー4：離職による知識の喪失

主要なエンジニアが離職し、その知識がドキュメント化されていない場合、チームは退職者と共に失われたコンテキスト（背景情報）を再構築するために生産性の低下を余儀なくされます。

入力項目：

• 年間の主要な離職者数

• 離職1回あたりの、チームの生産性低下が想定される期間（週数）

• 生産性低下期間中の、1週あたりのチーム全体のコスト

計算例： 年間離職2人 × 生産性低下期間6週間 × 週のチームコスト15,000ドル × 生産性低下30% = 年間 54,000ドル

カテゴリー5：コンテキスト不足によるエラー

エンジニアが「なぜシステムがそのように構築されたのか」を理解していなかったために発生するバグやミス。これらは最も数値化しにくいものですが、概念的な誤解は診断が難しく修正コストの高いバグを生み出すことが多いため、往々にして最も高くつきます。

入力項目：

• ドキュメントやコンテキストの不足に起因する、年間の想定インシデント件数

• インシデントあたりの平均コスト（診断、修正、レビューに要するエンジニアの時間）

計算例： 年間6件 × 平均コスト5,000ドル = 年間 30,000ドル

カテゴリー6：コンテキストなしで稼働するAIツール

AIコーディングツールや社内エージェント、自動化プロセスは、必要とするエンジニアリングのコンテキストがドキュメント化され、検索可能な状態になっていないため、本来の実力のわずかな割合しか発揮できていません。これは直接的なコストではなく機会損失であるため、最も数値化が困難なカテゴリーです。つまり、適切なコンテキストがある場合にAIツールが提供できる価値と、コンテキストがない状態で提供する価値の差です。

想定される影響： 包括的なドキュメントによってAIツールの効果が30〜50%向上し、チームが1日あたり2〜3時間をAIツールとのやり取りに費やしている場合、ドキュメント化されたコンテキストによって回復する生産性は、保守的な見積もりであっても大きな意味を持ちます。

合計金額の算出

採用ペースが緩やかで、ドキュメントの質が平均的な20人のエンジニアリングチームの場合：

これはAIの機会損失をカウントする前の数値です。20人のチームにおいて、質の悪いドキュメントによって生じる明確なコストは年間約50万ドルに達します。これは、包括的なドキュメントがあれば大部分を排除できたはずの問題に、エンジニア2〜3人分のリソースを費やしているのと同じことです。

比較

チームのGitHubでの活動、Slackでの会話、会議から自動的に作成・維持される自動作成ドキュメントの導入コストは、エンジニア1人分の給与のわずかな一部にすぎません。これにより上記のコストの50%でも削減できれば、投資収益率（ROI）はそのツールの導入コストの10倍から20倍に達します。

ほとんどのエンジニアリングリーダーにとって、問題は質の悪いドキュメントが高くつくかどうかではありません。個々のカテゴリーが、それぞれ単体では取るに足らないと感じられる数十の小さな非効率に分散しているため、これまで誰もそのコストを合算してこなかったことにあります。

それらは些細なことではありません。ただ、誰かが計算するまで見えていなかっただけなのです。

よくある質問

小規模なチームにとっても、これらの数字は現実的ですか？ 規模に比例して縮小して考えてください。採用や割り込みが少ない10人のチームであれば合計金額は低くなりますが、エンジニア1人あたりのコストは同様です。10人以上のほとんどのチームは、ドキュメントの問題によって年間10万ドル以上を失っています。チームが大きくなるにつれて暗黙知のボトルネックが悪化するため、このコストはチームの規模に対して非線形的に増加します。

すでにいくらかドキュメントがある場合はどうなりますか？ ドキュメントが充実している領域に応じて、見積もりを調整してください。オンボーディングのドキュメントは整備されているものの、決定事項のドキュメントが不足している場合、オンボーディングのコストは下がりますが、意思決定の蒸し返しコストは上がります。ほとんどのチームは、一部に優れたドキュメントがある一方で、大部分に大きなギャップを抱えています。

ドキュメントへの投資について、どのように経営陣を説得すればよいですか？ 上記のカテゴリーを用いて、あなたのチームの実際のデータで具体的な数値を算出してください。そして、それを解決策（ツールなど）のコストと並べて提示します。問題のコストが大きく、解決策のコストが比較的低いため、通常はROIの計算を示すだけで十分に説得力のある説明になります。

関連記事：エンジニアリングドキュメントを作成するコスト、エンジニアリングのオンボーディングにおける本当のコスト、バス係数について、優れたドキュメントは10倍の乗数効果を生む。関連ページ：ドキュメントの自動作成、エンジニアリングチーム向け、ナレッジの維持。