優れたドキュメントは、エンジニアリングの生産性を10倍にする掛け算の要素です。

ドキュメント作成の標準的な考え方は、それを読む人（新入社員、ジュニアエンジニア、馴染みのないコードベースを担当する同僚）を助けるためのものという定義です。これは事実ですが、方程式の反対側に焦点を当ててしまっているため、その恩恵を著しく過小評価しています。

はるかに大きな恩恵は、割り込みを受けなくなる人々にもたらされます。

割り込みによる損失

複雑な問題に取り組むシニアエンジニアには、持続的な集中力が必要です。コンテキストスイッチに関する研究では、一時的な割り込みであっても、その損失は割り込みそのものの時間よりはるかに大きいことが一貫して示されています。Gloria Mark氏の研究によると、割り込みの後に元の集中レベルに戻るための回復時間は約25分とされています。

優れたドキュメントがあれば解決するような質問によって、シニアエンジニアが1日に10回割り込みを受けると、回答にかかる10分間だけでなく、回復のための時間として約4時間の生産的な集中時間が失われることになります。これは、ドキュメントがないために労働時間の半分が失われていることを意味しますが、個々の割り込みは小さく対処可能に感じられるため、エンジニア自身も何が起きているのか気づかないことがよくあります。

質問自体はどれも完全に正当なものです。「なぜ認証サービスはこのような構造になっているのか？」「デプロイガイドはどこにあるのか？」「データベースではなく、このキューを使用した理由は何だったのか？」「データパイプラインは失敗したレコードをどのように処理するのか？」これらの質問すべてに答えは存在します。しかし、ドキュメントのないチームでは、その答えはシニアエンジニアの頭の中にしかなく、彼らの作業を中断させることでしか引き出すことができません。

掛け算の効果

優れたドキュメントは、チームの規模が大きくなるにつれて増大する掛け算の効果を生み出します。

5人のチームであれば、チームが小さく文脈が共有されているため、割り込みは管理可能です。しかし、シニアエンジニアが5人、そして彼らから文脈を定期的に得る必要のある人が15人いる20人のチームになると、割り込みの負荷は非線形に拡大します。各シニアエンジニアは3〜4人の質問のボトルネックとなり、シニアエンジニアの生産性に対する総損失は多大なものになります。

ドキュメントは、シニアエンジニアの関心を必要とせずにその知識を利用可能にすることで、このボトルネックを解消します。ジュニアエンジニアは質問する代わりにアーキテクチャドキュメントを読みます。新入社員は説明会を求める代わりにオンボーディングガイドに従います。馴染みのない領域を担当する同僚は、会議を設定する代わりに決定ログを読みます。

人からドキュメントへと質問を迂回させるたびに、質問者の待ち時間と回答者の割り込みコストが節約されます。チーム全体で1日に10個の質問があれば、節約される時間はシニアエンジニアの2〜4時間に相当します。これは、代理で質問に答えることだけを行うシニアエンジニアをもう一人雇うのと同じ効果を持ちます。

誰が最も恩恵を受けるか

優れたドキュメントから最も恩恵を受けるのは、通常、チームで最もシニアであり、最も価値のあるエンジニアです。彼らの時間は最も高価であり、その集中力は最も重要です。一方で、彼らはドキュメントを手動で作成する際に最も重いドキュメント作成の負担を背負う人々でもあります。これにより、非常に無駄の多い力学が生まれます。つまり、最も集中力が必要とされる人々が最も頻繁に割り込みを受け、その解決策（ドキュメント作成）も彼らに降りかかり、守るべき集中力をさらに削ってしまうのです。

自己生成型ドキュメントは、シニアエンジニアの既存のアウトプット（PRの説明文、Slackでの説明、ミーティングでの発言）からドキュメントを生成することで、彼らへの追加の負担を課すことなく、この悪循環を断ち切ります。彼らが文脈に応じてすでに共有している知識がキャプチャされ整理されるため、誰でも、いつでも、発信元を邪魔することなく見つけられるようになります。

よくある質問

割り込みの損失を測定するにはどうすればよいですか？ 1週間、シニアエンジニアがSlackのダイレクトメッセージや対面での依頼で受け取った質問の数を記録します。それに25分（1回の割り込みあたりの平均回復時間）を掛けて、失われた集中時間の合計を算出します。ほとんどのチームは、その数字が想定よりもはるかに大きいことに気づくでしょう。

ジュニアエンジニアがドキュメントを読んでくれないのでは？ ドキュメントが最新で、整理され、検索可能であれば、代替手段（シニアエンジニアの返答を待つこと）の方が遅いため、通常は高い確率で活用されます。ドキュメントが古くて信頼できない場合、エンジニアはいずれにせよ読みません。活用の度合いを決定するのは、ドキュメントの品質です。

これはドキュメントツールのコストを正当化しますか？ シニアエンジニアの給与を考慮すると、小規模なチーム全体で週にわずか2時間の集中時間を取り戻すだけでも、通常は市場にあるどのドキュメントツールのコストも上回ります。ROI（投資対効果）の計算はほぼ常にプラスであり、その効果はチームの規模とともに大きくなります。

関連記事：エンジニアリングドキュメントが重要な理由、エンジニアリングドキュメントを作成するコスト、属人化された知識の隠れたコスト。関連ページ：自己生成型ドキュメント、エンジニアリングチーム向け。