エンジニアリング文書の管理には年間50,000ドルものコストがかかっていますが、そのことは誰も話題にしません。

開発予算の中には、誰も考慮していない項目が存在します。それは、エンジニアがドキュメントの作成や維持管理に費やす時間です。これはプロジェクト計画には現れず、スプリントプランニングで見積もられることもなく、レトロスペクティブで議論されることも滅多にありません。しかし、それは現実に存在し、多大なコストがかかっており、ほとんどのチームにおいて、部門内で最も追跡されていない最大のコストの1つとなっています。

米国で年収180,000ドル〜220,000ドルを得ているシニアエンジニアは、福利厚生や経費を含めると、およそ1時間あたり85ドル〜105ドルのコストがかかります。同様の基準で、英国で年収80,000ポンド〜120,000ポンドを得ているシニアエンジニアは、およそ1時間あたり50ポンド〜75ポンドのコストがかかります。

もしそのエンジニアが週に5時間をドキュメント作成、Wikiページの執筆、アーキテクチャ図の更新、API変更の記録、コードではなく長文テキストでの意思決定の説明などに費やしている場合、米国での年間コストは22,000ドルから27,000ドルの間になります。10人のエンジニアからなるチームで、各自が週に3〜5時間をドキュメントに費やしているとすると、合計で年間130,000ドル〜270,000ドル相当のエンジニアリング時間が、構築ではなく執筆に費やされていることになります。

これらの数値は控えめに見積もられています。ドキュメントに記載されているべき内容をSlackで説明するために費やされた時間、ドキュメント化されなかった文脈をミーティングで再構築するために費やされた時間、あるいは新しいエンジニアが加わるたびに同じオンボーディングの質問に答えるために費やされた時間は含まれていません。

実際に時間がどこに消えているのか

週に5時間というのは、ドキュメント作成だけに集中する1つのまとまった時間ではありません。それは1週間の中で細切れに分散しており、それぞれに文脈切り替え（コンテキストスイッチ）のコストが発生しています。

プルリクエスト（PR）後のドキュメント作成。 意味のある変更をリリースした後、エンジニアはWiki、APIドキュメント、アーキテクチャ図、および関連するREADMEを更新します。これには重要なPR1件あたり30分から1時間かかることがありますが、コードから文章への文脈の切り替えは、時間だけでは測れないほどエネルギーを消耗するものです。

ドキュメントにあるべき質問への回答。 ジュニアエンジニアが、なぜ決済サービスがそのような構造になっているのかを尋ねます。プロダクトマネージャーが、データパイプラインがどのように機能するのかを尋ねます。新入社員が、デプロイガイドがどこにあるかを尋ねます。それぞれの質問への対応には10〜20分かかり、回答は口頭で行われるか、数日以内に流れて消えてしまうSlackのスレッドで行われます。

既存ドキュメントの維持管理。 リファクタリングによって3つのWikiページが不正確になります。APIの変更によってインテグレーションガイドが無効になります。依存関係のアップデートによってセットアップ手順が動かなくなります。誰かがこれらを見つけて修正しなければなりませんが、その作業は退屈であるため、誰かが古い手順に従って午後の時間を無駄にするまで放置されることがよくあります。

オンボーディングドキュメント。 新メンバーが入社するたびに、チームは自分たちの頭の中にあった知識を、文脈を共有していない人のために書き留める必要があることに気づき、ドキュメント作成活動が突発的に発生します。これは、時間的プレッシャーの中で作成され、不完全であることが多く、新メンバーがそれを必要としなくなった後はほとんど維持管理されないという、最もコストのかかる「事後対応型」のドキュメント作成です。

機会費用（オポチュニティコスト）

ドキュメント作成のコストは、単に給与分の時間だけではありません。その時間が、代わりに何に使えたはずだったかという点も重要です。

シニアエンジニアの週5時間は、アーキテクチャの検討、コードレビュー、メンタリング、デバッグ、または機能開発に充てられたはずの5時間です。1人のエンジニアにとって、1年間で約250時間、つまり丸6週間のフルタイム労働に相当する時間が、本来採用された目的である業務から逸れてしまっているのです。

機会費用を最も痛感するのは、通常、最も経験豊富なシニアエンジニアです。なぜなら、彼らこそがドキュメント化すべき最も多くの文脈を持ち、かつ、その時間に対して最も価値の高い代替の使い道を持っているからです。ドキュメント作成の負担は、組織にとって最も邪魔されたくない人材に最も重くのしかかります。

代替案

上記のコスト計算は、ドキュメント作成には人間のエンジニアの時間が必要であるという前提に基づいています。これはソフトウェアエンジニアリングが存在する限り真実でした。しかし、自動生成ドキュメント（自己記述型ドキュメント）はこの前提を変えます。

すでに発生しているエンジニアリング活動からドキュメントが自動的に生成・維持されるようになると、現在あなた方の知識を一時的な形で保持しているソース（GitHubのPRやコミット、Slackでの会話、ミーティングの録画、設計書など）を活用することで、人間が執筆するコストはほぼゼロにまで低下します。

エンジニアは、生成されたドキュメントを確認し、不正確な箇所を修正し、自動システムが逃した文脈を追加するだけで済みます。しかし、組織の活動を構造化され検索可能なドキュメントへと変換するベースとなる作業は、時給85ドル〜105ドルの人々ではなく、システムによって処理されます。

10人のエンジニアからなるチームで各自が週に5時間をドキュメントに費やしている場合、その手作業のわずか80%を削減するだけで、年間100,000ドル〜215,000ドルのエンジニアリング時間を回収できます。これは、すでに雇用しているエンジニアの時間を無駄にしないことで完全に賄われる、追加のエンジニアをもう1人採用するのと同等の効果です。

よくある質問

週5時間というのは現実的ですか？ エンジニアリングチームへの調査では、シニアエンジニアのドキュメント作成時間は一貫して週4〜8時間とされており、オンボーディング期間や大規模なリファクタリングの後にはこの数字がさらに上昇します。5時間というのは控えめな見積もりであり、実際に追跡してみると、多くのチームで実際の数字はもっと高くなるはずです。

ドキュメントをまったく書かないチームはどうなりますか？ 彼らは別の形でそのコストを支払っています。すなわち、より長いオンボーディング時間、シニアエンジニアへのより頻繁な割り込み、アーキテクチャの誤解によるより多くのエラー、そしてメンバーが離職した際のより深刻な知識の喪失です。ドキュメントを書かないコストは、多くの場合、書くコストよりも高くなります。ただ、それは1つの予算項目として現れるのではなく、何十もの小さな非効率性に分散しているため、目立ちにくいだけです。

自分のチームのコストはどのように計算すればよいですか？ エンジニアの人数を数え、ドキュメント関連の活動（執筆、維持、ドキュメントにあるべき質問への回答）に費やす平均的な週労働時間を見積もり、そこに諸経費を含めた時間単価を掛けます。実際に計算してみると、ほとんどのチームがその数字の大きさに驚かされます。

関連する読み物： なぜエンジニアリングドキュメントが重要なのか、 なぜエンジニアはドキュメントを書くのが嫌いなのか、 質の悪いドキュメントによってどれほどのコストが発生しているか？。 関連ページ： 自動生成ドキュメント、 エンジニアリングチーム向け。