エンジニアがドキュメント作成を嫌う理由（そして彼らの主張が正しい理由）

開発チームにドキュメントをもっと書かせようとしたことがある人なら、それがどうなるかよく分かっているはずです。命令の直後は一時的にルールが守られ、いくつかのWikiページが作成または更新されますが、1か月もしないうちにチームは以前の状態に戻ってしまいます。ドキュメント化の取り組みは、定着しなかった「善意のプロセス」のコレクションに加わるだけです。

一般的なマネジメント層の解釈は、「エンジニアはドキュメント作成を怠けている」、あるいは「その重要性を理解していない」というものです。この解釈は間違っており、これに基づいたポリシーを構築すると、まったく同じ構造的な理由で何度も失敗する取り組みが生み出されることになります。

エンジニアがドキュメント作成に抵抗するのは、彼らの反対意見が正しいからです。

本当の反対理由

コンテキストスイッチのコストが高い。 文章を書くことと、コードを書くことでは、異なる認知モードを使用します。デバッグやアーキテクチャに必要な緻密で論理的な思考から、ドキュメントに必要な説明的で読者を意識した思考へと切り替えることは、タイムシートには表れない形で疲弊を伴います。ほとんどのエンジニアは、Wikiページに30分費やした後にコードに戻るための20分など、コンテキストの切り替え自体に、執筆そのもの以上のコストがかかると報告しています。

ステータスが低いと感じられる。 ほとんどの開発カルチャーにおいて、コードをリリースすることはステータスが高く、コードについて書くことはそうではありません。Wikiへの貢献で昇進する人はいません。人事評価でアーキテクチャドキュメントの品質が強調されることもありません。インセンティブ構造はエンジニアに「ドキュメントは構築することの二の次である」と伝えており、彼らはそのインセンティブに合理的に反応しているだけです。

数週間で古くなることを知っている。 これは、ほとんどのマネージャーが無視し、ほとんどのエンジニアが最も強く感じている反対意見です。せっかく丁寧に書いたアーキテクチャドキュメントが、数スプリントの変更を経て不正確になるのを見てきたエンジニアは、ドキュメント作成の労力の半減期が短いことを学びます。急速に劣化するものに対して、労力を増やすのではなく、減らすのが合理的な反応です。

ターゲット読者が不明確である。 これらのドキュメントは誰のためのものでしょうか？ 将来のエンジニア？ システムをすでに知っている現在のチームメイト？ それともプロダクトマネージャー？ 読者によって、適切な詳細レベル、構成、技術的な深さは完全に異なります。読者が明確でないため、エンジニアは間違ったレベルで書いてしまうか、あるいは曖昧さのためにタスクが果てしなく感じられて何も書かなくなります。

なぜモチベーションを高めても解決しないのか

これらの反対意見がモチベーションではなく構造的なものであると理解することで、解決策のあり方が変わります。

モチベーションを高めるアプローチ（ドキュメントの義務化、スプリント要件への追加、貢献度のゲーム化など）は、一時的な追従は生み出しますが、エンジニアが抵抗する根本的な理由には対処できません。コンテキストの切り替えコストは依然として高く、ステータスの階層も変わらず、ドキュメントはやはり古くなります。

実際に機能するアプローチは、モチベーションではなく構造に対処するものです。

エンジニアを執筆のループから外す。 自己執筆型ドキュメントは、すでに発生しているエンジニアリング活動（意思決定が議論されるSlackでの会話や、アーキテクチャが議論されるミーティング、PRの説明やコミットメッセージなど）から構造化されたドキュメントを生成します。エンジニアの貢献は業務そのものであり、ドキュメントは追加のタスクではなく副産物となります。

ドキュメントを自動的に最新の状態に保つ。 元となるコードや会話が変化するにつれてドキュメントが自動的に更新されれば、「古くなる」という反対意見は解消されます。エンジニアは、大部分が正確であると信頼できるドキュメントであれば、レビューして洗練させることを厭いません。1ヶ月以内に間違いになると分かっているドキュメントは書きたがらないのです。

フォーマットによって読者を明確にする。 定義されていない読者のために書くようエンジニアに求める代わりに、構造化されたフォーマットを提供します。たとえば、アーキテクチャの決定には決定ログ、新入社員にはオンボーディングドキュメント、システムドキュメントには開発Wikiなどです。各フォーマットはそれぞれの読者を暗示しているため、執筆（またはレビュー）タスクがオープンエンドではなく、限定されたものになります。

レビューモデル

最も持続可能なドキュメントモデルは、エンジニアを著者ではなくレビュアーとして扱うものです。システムは、利用可能な情報源（コードのアクティビティ、会話、ミーティング）から初期ドキュメントを生成します。エンジニアはそれをレビューし、修正し、肉付けします。レビューは2時間の執筆セッションではなく10分のタスクであり、コンテキストの切り替えは最小限で済みます。また、エンジニアの貢献はゼロからの作成ではなく、すでに存在するものに対する品質保証になります。

このモデルはエンジニアの時間を尊重し、彼らの懸念に対処し、最新に保たれるドキュメントを生み出します。また、生成されたドキュメントは網羅的（エンジニアが書き留めることを覚えていた内容ではなく、発生したすべての出来事をキャプチャするため）かつ一貫している（著者によってばらつきがなく、標準フォーマットに従うため）ため、手動で作成するよりも優れたドキュメントになる傾向があります。

よくある質問

実際にドキュメント作成を楽しむエンジニアについてはどうですか？ そういうエンジニアは存在しますし、非常に貴重です。レビューモデルにおいて、彼らは自動化システムでは作成できないニュアンス、コンテキスト、ストーリーを加え、生成されたドキュメントをより豊かで優れたものにする役割を担います。彼らのスキルは、システムが処理できる基本的な執筆作業ではなく、ドキュメントを豊かにすることに活用すべきです。

エンジニアはAIが生成したドキュメントを信頼するでしょうか？ 思っている以上にすんなりと受け入れるでしょう。なぜなら、そのドキュメントは、自分たちのPR、Slackスレッド、ミーティングでの議論など、エンジニア自身が認識している情報源から生成されているからです。ドキュメントにはこれらの情報源が引用されているため、エンジニアは元の情報を確認して内容を検証できます。信頼は透明性の上に築かれ、引用に裏付けられた生成プロセスがそれを提供します。

機密情報や機密性の高い情報はどのように扱いますか？ システムは、キャプチャする対象について設定可能な境界線を持つ必要があります。特定のSlackチャンネル、特定のレポジトリ、または特定のミーティングカテゴリを除外することができます。エンジニアはシステムが何を閲覧できるかをコントロールできるため、機密情報が生成されたドキュメントに入り込むのを防ぐことができます。

関連記事：開発ドキュメント作成のコスト、ドキュメンテーションのパラドックス、自己執筆型ドキュメントの解説。関連ページ：自己執筆型ドキュメント、開発チーム向け。