機械の中の幽霊：AIはコードを書けるが、「組織的負債」の文書化には惨めに失敗する理由

最近、LinkedInのフィードが「AIがテクニカルライターに取って代わっている」という投稿で溢れています。その論理は、「ChatGPTがコードを書けるなら、READMEファイルも簡単に書けるはずだ」というものです。

実際のコードベースに携わる者として、私の答えはシンプルです。いいえ、そんなことはできません。人々はドキュメントの本質を見誤っています。AIは構文を理解できますが、「組織的負債」への対処には完全に失敗します。

「ジャガード」の現実

正直に言いましょう。現実の世界では、ソフトウェアアーキテクチャは完璧なことは稀です。厳しい納期の下で、開発者はきれいなコードを書かず、サーバーを金曜夜に稼働させるためだけに、迅速なパッチや一時的な回避策——いわゆるジャガード——をデプロイします。

彼らはいつも「来週これをドキュメント化する」と言う。しかし、来週は決して訪れません。

開発者の頭の中にあるこの隠れた、書かれていない知識が「組織的負債（Institutional Debt）」または「部族知（Tribal Knowledge）」です。そして、ここでAIは壁にぶつかります。

AIは「何」を知るが、「なぜ」を知らない

乱雑なコードベースをAIに与えれば、コードが何をしているのかを喜んで教えてくれます。関数や変数を完璧に説明してくれます。
しかし、AIはなぜその特定の回避策が3年前に作られたのかを決して教えてくれません。

日曜ごとにAPIをクラッシュさせる奇妙なレガシーサーバーバグについては知りません。
チームにそのパッチを使わせた過去のアーキテクチャ上の失敗の歴史も知りません。
構文だけに基づいてAIにそのコードを最適化させたり書き換えさせたりすることを盲目的に信じれば、システムは壊れるでしょう。AIには、なぜその混沌が存在するのかという人間の文脈が欠けています。

ライターは「ソフトウェア探偵」

テクニカルライティングは、Markdownファイルのフォーマットや良い英語を知っているだけではありません。

優れたテクニカルライターは探偵です。私たちの本当の仕事は、疲れたシニアエンジニアと電話をし、正しい質問をして、彼らが退職する前にその部族知を掘り出すことです。

シニア開発者が去るとき、彼らは会社の文書化されていない知識の一部を持ち去ります。AIはこの頭脳流出を止めることはできません。人間のライターなら止められます。

結論

AIは機械のために書きます。人間は他の人間のために意思決定を文書化します。

したがって、次に技術リーダーが予算を節約するためにAIでライターを置き換えることを考えたとき、自問すべきです。あなたのAIは、文書化されていないレガシーバグが原因で本番環境がクラッシュしたときに、責任を取る準備ができているでしょうか？

おそらく、できていないでしょう。