地図、金、スパイス: ドキュメント作成を怠るとプロジェクトが失敗する理由

昔の探検家たちが航海から持ち帰った最も貴重な財産は何だったでしょうか? 金と香辛料? 違います。地図です。

クリストファー・コロンブスは1492年に有名な航海を成し遂げることができなかっただろう。 地図先人たちが設計した。ポルトガルの地図を手に入れるためのスパイゲームは、人類史上最も高価な会社とも言えるオランダ東インド会社の基盤となった。1637年のピーク時には、その価値は7800万オランダグルデンで、これは1940年代のオランダの通貨に匹敵する。 7.9兆ドル2017年のドル換算で10兆ドル以上となり、マイクロソフト、エヌビディア、アップルの3社を上回る。 組み合わせた新しい土地から得られる明白な宝物は短期的には重要でしたが、より長い視点で見ると、本当の財産を築いたのは知識でした。

今日のテクノロジーの世界では、なぜ私たちはこれを忘れがちになるのでしょうか。私たちは、目先の成功を追い求め、技術文書の作成と維持に貴重な時間とリソースを費やすことを躊躇しがちです。17 世紀の言葉で言えば、地図を描くことなく金やスパイスを急いで手に入れようとしますが、地図を描けば、さらに多くの金やスパイスを手に入れることができたはずです。あなたは懐疑的ですか? では、詳しく見てみましょう...

奇妙なコード

「あなたもきっと覚えているでしょうが、脳のニューロン パターンの催眠状態は、超電磁ビームでスキャンできます。それは ―」 「冗談じゃない!」アード ヴァークはいらいらしながら言いました。「私たちが間違いなく覚えているという意味ですか?」 知らなかったのに、どうして覚えていられるというのでしょう? - これは、偉大な SF 作家エドモンド ハミルトンの小説「Wacky World」からの引用で、プログラマーではなく火星人について述べています。しかし、開発者を別の惑星から来たかのように見ている人は多く、特にソフトウェア開発とその複雑さについて漠然とした知識しか持っていない人はそうです。実際、開発者は他の人も自分と同じくらいコードを知っていると思い込んでおり、技術ドキュメントは不要であると考えることがよくあります。この考え方は、プロジェクトを「催眠状態」と同じくらい複雑で部外者にとって理解不能なものにし、最終的にプロジェクトの潜在的な成功を危うくするリスクがあります。

ドキュメント作成をためらう理由は、多くの場合、他の分野で先延ばしにするのと同じ理由から生じます。つまり、ドキュメント作成にはかなりの時間と資金の投資が必要です。言い換えれば、単なる怠惰と節約願望が原因であることが多く、これらは簡単に克服できる障害ではありません。ただし、ドキュメントは、誰にとっても明らかであるはずの冗長な情報だけではありません。不可欠な重要な詳細が含まれています。多くの場合、ドキュメントがないと、エラーの検出と修正が大幅に複雑になり、メンテナンスと更新が難しくなり、新しいチームメンバーのオンボーディングに必要な時間が長くなります。ドキュメントのないチームは反復的なタスクに悩まされていますが、適切に構造化されたドキュメントを持つプロジェクトは高い効率性と信頼性を示します。これは単なる意見ではなく事実です。

確かに、プログラマーの中には、自分が書いたコードは非常に明確で理解しやすいので、ドキュメントはまったく不要だと主張する人もいます。しかし、実際には、最も完璧なコードでも、他の人を混乱させたり、時間が経つにつれて明確さを失ったりすることがあります。今日は明確だと思われるものでも、明日はパズルになることがあります。たとえば、1970 年代の単純なパンチ カードを簡単に扱えるでしょうか?

バスファクター、バーンアウト、その他の素晴らしい獣たち

理論は良いですが、実践の方が説得力があります。ここに、実話に基づいたいくつかの例を示します。人物と会社名は架空のものです。これらの簡単なケース スタディでは、技術文書の不適切な作成方法によって生じる最も一般的な問題を取り上げます。

ストーリー＃1：スケールできない

当初は成功したビデオストリーミングのスタートアップだったプロジェクト「NoDocumentationPlease」は、技術文書が不十分だったため、規模を拡大しようとしたときに深刻な問題に直面しました。チームを拡大する必要が生じたとき、新入社員は自分の仕事を完全に理解できず、誰も彼らに適切な説明を提供できませんでした。適切なサポートとトレーニングがなかったため、新入社員はすぐに辞めてしまいました。これにより、プロジェクトの進行が遅れただけでなく、重要な人材が失われ、最終的にはプロジェクト全体の有効性と将来性が危うくなりました。その結果、ストリーマーはチャットを離れ、プロジェクトは閉鎖されました。

ストーリー2: メンテナンスの問題

「IKnowEverything」という会社は、データの同期と保存のためのクラウド プラットフォームを開発しました。当初、プロジェクトは急速に進みましたが、時間が経つにつれて、明確で最新の技術ドキュメントが不足していたため、開発者はプラットフォームの保守と更新に困難に直面しました。これにより、開発が遅くなり、バグが増え、顧客の不満が高まりました。最終的に、同社は古い顧客を失い始め、新しい顧客はより安定して信頼性の高いソリューションを提供する競合他社を選択しました。収益は大幅に減少し、非効率的な保守のコストは増加しました。最初から技術的な側面を適切に文書化しておけば、うまく拡張できた可能性があります。しかし、それは間に合いませんでした。その結果、同社は技術的および財務的な課題を克服できず、閉鎖されました。

ストーリー#3: 開発者の燃え尽き症候群

「SmartestEver」プロジェクトは、ほぼすべての作業を担当していたメイン開発者の Andrew が、チームからの多数の質問に圧倒されて辞職したため、深刻な問題に直面しました。「SmartestEver」に適切なドキュメントがあれば、ジュニア開発者は FAQ を簡単に参照して、日常的な問題を解決できたでしょう。しかし、彼らは Andrew に質問を浴びせかけ、Andrewと必要なドキュメントがなくなったため、チームは続行できなくなり、プロジェクトは終了しました (Andrew の場合は F を押します)。

ストーリー#4: バス要因

「NoDocsNeeded」という会社では、有望なソフトウェア製品が、主要な開発者であるジョンによって開発されていました。ジョンは、あらゆる知識を持っていましたが、それを文書化しようとはしませんでした。彼の上司も、ジョンを説得しようとはしませんでした。ある日、ジョンは出張に出かけ、戻ってきませんでした。製品のアーキテクチャとロジックに関する文書化や理解がなければ、残りのチーム メンバーは基本的に何もできませんでした。プロジェクトは凍結され、投資したお金は無駄になりました。教訓は単純です。チーム内での文書化と知識の分配は、1 人の人物への依存を避けるために不可欠です。ところで、彼らはまだジョンを探しています...

ストーリー#5: オープンソースでは預言者は歓迎されない

マリアは最初のオープンソース ライブラリを作成しましたが、それに関するドキュメントは何も書いていませんでした。誰もそのライブラリの機能を理解しておらず、マリアはそれが無意味に思えたため、これ以上ライブラリを作成しないことに決めました。マリアのプロジェクトは開始前に終了し、彼女は職業を変えることを決意しました。

キャビンボーイから船長へ

さて、理論と実践は理解できました。次は研究と統計について見ていきましょう。Stack Overflow 開発者アンケート 2024州回答者の 84% が技術ドキュメントを使用してテクノロジの機能を理解しています。ただし、ドキュメントを使用しても、必要な回答が見つからないことがよくあります。次に人気のリソースは、Stack Overflow (80%)、チュートリアル (68%)、ブログ (61%)、ハウツー ビデオ (54%) です。Microsoft Research: ソフトウェア開発者の日常生活 見つかった平均して、開発者は 1 日の 1 ～ 2% (8 ～ 10 分) をドキュメント作成に費やしており、開発者の 10.3% は、ドキュメントが古すぎるために自分で答えを探すのに時間がかかりすぎると回答しています。ドキュメントの必要性は、学術界にとっても大きな懸念事項です。Google Scholar で <"documentation" AND "software"> を検索すると、 収穫400 万件を超える結果が見つかり、この問題を扱った膨大な数の科学出版物が存在することが明らかになりました。

主な結論は驚くほどシンプルです。#1 - 技術や他の人の仕事を理解するには、誰もがドキュメントを必要とします。しかし、#2 - ドキュメントの作成と維持に気を配る人はほとんどいません。その結果、#3 - 多くのドキュメントは質の低い内容で、古く、一般的に役に立たない内容になっています。では、何をすべきでしょうか。あらゆるレベルでモチベーションを変えることです。

HAN応用科学大学とフローニンゲン大学（ともにオランダ）の研究者グループ特定された技術文書に関する最も一般的な問題:

• 開発者がよく使用する非公式のドキュメントは理解しにくいものです。

• ドキュメントは、最終製品に直接貢献しない場合は無駄とみなされます。

• 開発者の生産性は動作するソフトウェアの量のみで測定されます。

• ドキュメントは実際のソフトウェアと同期していないことがよくあります。

• 特に継続的なソフトウェア開発環境では、開発者は短期的な焦点のみを維持することがよくあります。

  
  

これらのうち、聞き覚えのあるものはありませんか?私たちのほとんどは、日常業務の中で、これらのほとんど、あるいはすべてに一度は遭遇したことがあるはずです。そして、それは単に先延ばしやリソース不足だけではありません。これらの問題の一部は、適切な管理、長期計画、そして最終的には戦略的ビジョンの欠如から生じています。そして、ここからが困難な部分です。なぜなら、それを解決するのは私たち開発者だけではないからです。一部の問題は、マネージャー、製品の利害関係者、さらには会社の所有者が対処する必要があります。だからこそ、技術に関する適切な見解は、単なる素敵な付属品ではなく、創業者からジュニア開発者まで全員が共有する会社全体のコアバリューの一部であることが重要です。