【海外エンジニアの生存戦略】ドキュメント地獄へようこそ：「完璧」がプロジェクトを殺すとき

  1. 安心という名の幻想、あるいは「テキストの壁」が築かれるまで
    1. ～The Illusion of Security: Why We Build Walls of Text～
    2. 海外のオフィスから愛を込めて
    3. 「The Documentation Dilemma」との遭遇
    4. 「完全」という言葉の重力
    5. 現場で起き始めた異変
    6. なぜ「More」が失敗するのか
    7. 序章の終わりに：埋没費用（サンクコスト）の罠
  2. ドキュメントという名の「足枷」
    1. ～Real-world examples of documentation becoming a project bottleneck～
    2. 終わらない「スクリーンショット」の悪夢
    3. 「バインディング」の嘘と、時間の浪費
    4. 「レビュー」という名の儀式
    5. リファクタリングへの恐怖と技術的負債
    6. 決定的な事件：緊急パッチのパラドックス
  3. 地下組織としての「ドキュメント改革」
    1. ～The hidden costs of over-documentation: time, morale, and stagnation～
    2. 限界点と「地下活動」の始まり
    3. 武器その１：XMLコメントとDocFXの導入
    4. 武器その２：WPFにおける「Design-Time Data」
    5. 武器その３：ユニットテストを「仕様書」にする
    6. 審判の日：Daveとの対決
    7. パラダイムシフト：「What」ではなく「Why」を書く
    8. 英語力とネーミングセンスの向上
    9. 転の終わりに：自由を取り戻したエンジニアたち
  4. 完璧主義を捨て、実用主義の荒野へ
    1. ～The hidden costs of over-documentation: time, morale, and stagnation～
    2. プロジェクトのその後：Daveの変心
    3. 法則1：日本の「完璧主義」をアップデートせよ
    4. 法則2：「What」ではなく「Why」だけを書け
    5. 法則3：英語力が低いなら、コードを「雄弁」にしろ
    6. 法則4：自動化できないルールは、いつか破綻する
    7. 法則5：ドキュメントは「信頼」の代替品である
    8. 最後に：あなたへのメッセージ

安心という名の幻想、あるいは「テキストの壁」が築かれるまで

～The Illusion of Security: Why We Build Walls of Text～

海外のオフィスから愛を込めて

今、僕はオフィスの窓から見える曇り空を眺めながら、片手にぬるくなったコーヒーを持ってこれを書いています。こっち（海外）の天気は変わりやすい。まるで僕らが相手にしている顧客の要件みたいにね。

普段、僕はC#とWPF（Windows Presentation Foundation）を使って、かなり大規模な業務系アプリケーションのアーキテクチャ設計や実装を行っています。WPFって、XAMLの柔軟性とデータバインディングの強力さが魅力ですが、MVVMパターンを厳密に適用しようとすると、構造が複雑になりがちですよね。View、ViewModel、Model、そしてBehaviorやConverter……。これらがどう絡み合っているか、コードを見ただけでは瞬時に理解できないこともあります。

だからこそ、「ドキュメント」が必要になる。それは万国共通の真理です。

僕も日本で働いていた頃は、「神は細部に宿る」を地で行くような、緻密な詳細設計書をExcel方眼紙に書き込んでいました。「誰が読んでも同じものが作れるように」というのが当時の正義。そして、海外に出れば、きっと合理的で、必要最低限のドキュメントで、アジャイルにバリバリ回しているんだろうな……なんて、淡い期待を抱いていたんです。

でも、現実は違いました。

ここ海外でも、あるいは海外だからこそ、「ドキュメント」は時に「信仰」の対象になり、時に「免罪符」になり、そして最悪の場合、プロジェクトを圧死させる「凶器」になるんです。

「The Documentation Dilemma」との遭遇

僕がこの問題――名付けて**「The Documentation Dilemma（ドキュメンテーションのジレンマ）」**――に正面から衝突したのは、あるレガシーシステムのマイグレーション案件でした。

WinFormsで書かれた15年モノのスパゲッティコードを、最新の.NETとWPFで刷新するという、エンジニアなら武者震い（あるいは悪寒）がするようなプロジェクト。チームは多国籍。アメリカ、インド、東欧、そして僕（日本）。

プロジェクトのキックオフで、リードアーキテクトの「Dave（仮名）」が高らかに宣言しました。

「我々は過去の失敗から学ばなければならない。このシステムがメンテナンス不能になったのは、ドキュメントがなかったからだ。今回は、完全なドキュメントを作成する。コードを書く前に、すべてを定義するんだ」

皆が頷きました。僕も頷きました。「やっぱり海外のエンジニアはプロフェッショナルだ。基礎を大事にするんだな」と感心すらしました。

しかし、それが地獄の入り口だったのです。

「完全」という言葉の重力

Daveが求めた「完全（Complete）」の意味を、僕たちはまだ理解していませんでした。

それは、「クラス図を書く」とか「API仕様書を残す」といったレベルの話ではありませんでした。画面のすべてのボタン、すべてのテキストボックス、バリデーションのロジック、例外処理、果てはXAMLのStyle定義の意図に至るまで、すべてをWiki（Confluenceのようなツール）とWordドキュメントに記述することを指していたのです。

「More Isn’t Always More（多ければいいってもんじゃない）」。

今の僕ならそう言えます。でも当時は、「情報は多ければ多いほど、後の助けになるはずだ」という直感を信じて疑いませんでした。特に我々日本人エンジニアには、「記録を残す」という文化的な几帳面さがあります。これが、このプロジェクトの方針と最悪の化学反応を起こしました。

僕はWPFの特性上、UIの挙動とデータバインディングの関係性を事細かに記述し始めました。

「このTextBoxのTextプロパティは、ViewModelのCustomerNameプロパティにTwoWayでバインドされ、UpdateSourceTriggerはPropertyChangedである。なぜなら……」

こんな調子です。最初は順調でした。ドキュメントが増えるにつれ、なんとなく「仕事をした気」になれるんです。成果物が目に見える形で積み上がっていく（デジタルの山ですが）のは、ある種の快感でもありました。

「これで、誰がいつプロジェクトに参加しても大丈夫だ。完璧な地図があるんだから」

僕たちは、自分たちが作り上げているのが「地図」ではなく、足を踏み入れたら二度と出られない「迷宮」だということに気づいていませんでした。

現場で起き始めた異変

プロジェクト開始から3ヶ月。異変は静かに、しかし確実に進行していました。

まず、「読むコスト」の爆発です。

新しくチームに入ったメンバーが、WPFの特定の機能修正を任されました。「ドキュメントを見てくれ」と伝えると、彼は3日後に青い顔をして戻ってきました。「関連するページが20ページあって、それぞれ記述が微妙に食い違っている。どれが正解なんだ？」

次に、**「変更への恐怖」**です。

アジャイル開発を謳っていたはずなのに、仕様変更の話が出るたびにチーム全体が重苦しい空気に包まれるようになりました。コードを直すのは一瞬です。C#のリファクタリング機能を使えば数分で終わる。でも、それに付随する「ドキュメントの修正」に数時間、あるいは数日かかるのです。スクリーンショットを撮り直し、説明文を書き換え、相互リンクを確認する……。

エンジニアたちは次第に、こう考えるようになりました。

「この機能改善、ユーザーには役立つけど、ドキュメント直すの面倒だから提案するのはやめておこう」

恐ろしいことだと思いませんか？ ドキュメントを守るために、プロダクトの価値を犠牲にし始めたのです。

なぜ「More」が失敗するのか

ここで、少し視点を抽象化してみましょう。なぜ「完全なドキュメント」を目指すと失敗するのでしょうか？

それは、ソフトウェア開発というものの本質に関わっています。ソフトウェアは「Soft（柔らかい）」ものであるはずです。常に変化し、環境に適応し、成長していくもの。しかし、過剰なドキュメントは、その柔らかい実体を「Hard（硬い）」コンクリートで固めてしまうような行為なんです。

特にWPFのような技術スタックでは、UIとロジックの分離が進んでいます。XAMLで書かれたViewはデザイナーやUIエンジニアの領域、ViewModelはロジック担当の領域、といった具合に分業もしやすい。

しかし、それを「文章」ですべて繋ぎ止めようとすると、情報の重複（Redundancy）が大量に発生します。コード（XAML/C#）自体が「仕様」を語っているのに、それを自然言語（英語や日本語）で翻訳して書き写す行為。これは、「コード」と「ドキュメント」という二つの異なるソースコードをメンテナンスしているようなものです。

二重管理は、必ず破綻します。片方が更新され、片方が忘れ去られる。そして、「嘘をついているドキュメント」が生まれる。

「嘘のドキュメント」ほど、エンジニアを混乱させ、時間を奪うものはありません。ソースコードを見ればIsVisibleがfalseなのに、ドキュメントには「常に表示される」と書いてある。この矛盾を解決するために費やされる調査時間は、まさに人生の無駄遣いです。

序章の終わりに：埋没費用（サンクコスト）の罠

「起」のパートの締めくくりとして、当時の僕の心境をお話しします。

プロジェクトが半年を過ぎた頃、僕は薄々気づいていました。「このドキュメント、誰も読んでないんじゃないか？」と。

でも、止まれなかった。なぜなら、すでに膨大な時間をそのドキュメント作成に費やしていたからです。「これだけ書いたんだから、無駄にはできない」「今やめたら、これまでの努力が水の泡だ」。典型的なサンクコストの罠です。

さらに悪いことに、海外の契約社会的な側面も顔を出しました。

「要件定義書に書いてある通りに作ったか？」

「ドキュメントに記載がない挙動はバグだ」

ドキュメントは、開発のためのツールから、責任回避のための「盾」へと変貌していました。エンジニアたちは、クリエイティブな解決策を考える時間よりも、「自分の身を守るための文章」を書く時間に多くを割くようになっていました。

オフィスのホワイトボードには、複雑なアーキテクチャ図が消されずに残っていましたが、誰もそれを見なくなっていました。みんな、自分のモニターの中にあるWordドキュメントの「変更履歴」と睨めっこしていたのです。

「これが、僕が海外でやりたかったエンジニアリングなのか？」

自問自答の日々。しかし、この重苦しい空気を打ち破る出来事が、プロジェクトの後半で起こります。それはまさに、ドキュメントという名の巨塔が崩れ去る瞬間でした。

次回の「承」パートでは、実際にこの過剰なドキュメントがどのようにプロジェクトのボトルネックとなり、具体的な「事件」を引き起こしたのか。そして、WPF開発特有の「あの機能」が、いかにしてドキュメントとの相性の悪さを露呈させたのか。その生々しい現場の様子を描写していきます。

皆さんの現場にも、「誰も読まないWiki」や「更新日が3年前の仕様書」はありませんか？ もしあるなら、この先の話はきっと他人事ではないはずです。

ドキュメントという名の「足枷」

～Real-world examples of documentation becoming a project bottleneck～

終わらない「スクリーンショット」の悪夢

プロジェクトも中盤に差し掛かった頃、僕たちを襲った最初の悲劇は、技術的な難問ではなく、あまりにも原始的な作業でした。

**「UI仕様書のスクリーンショット更新地獄」**です。

WPFで作るモダンなUIは、非常に柔軟です。スタイルやテンプレート（ControlTemplate）を少し調整するだけで、アプリ全体のルック＆フィールを劇的に変えることができます。ある日、デザイナーが「プライマリーカラーの青を、もう少し落ち着いたネイビーに変更したい」と言い出しました。

WPFなら、App.xamlのリソースディクショナリでSolidColorBrushを一行書き換えるだけ。修正作業はたったの30秒です。

しかし、Daveが定めた「完全なドキュメント」のルールが、ここに立ちはだかりました。

「仕様書には、最新の画面状態を貼り付けること」

僕たちが管理していた画面数は約60画面。さらに、それぞれの画面には「通常時」「マウスオーバー時」「無効（Disable）時」「バリデーションエラー時」の各状態の記述が求められていました。

たった一行のコード変更のために、僕たちエンジニア3人は、丸2日間、ひたすらアプリを起動し、該当箇所を表示させ、Win + Shift + Sでスクショを撮り、Wordに貼り付けるという作業を強いられました。

「これ、俺たちがやる仕事か？」

隣の席のハンガリー人エンジニア、ピーターが溜め息交じりに呟きました。彼の時給は決して安くありません。高度なアルゴリズムを書ける頭脳が、ただのコピペマシーンとして消費されている。

隠れたコストその１：優秀な人材のモチベーション破壊

エンジニアにとって最大の報酬は「問題を解決すること」や「新しいものを作ること」です。無意味な事務作業は、彼らの魂を削ります。この一件以降、ピーターのコミット数は目に見えて減り始めました。

「バインディング」の嘘と、時間の浪費

WPFや、昨今のReact/Vueなどのフレームワークにおける最大の特徴は、「データバインディング」です。画面（View）とロジック（ViewModel）は疎結合になっており、データの流れは背後で動的に行われます。

ある日、僕は複雑なデータグリッドのバグ修正を担当しました。顧客一覧を表示するグリッドで、特定の条件下でソートが効かないというバグです。

ルール通り、僕はまず「仕様書」を開きました。そこにはこう書かれていました。

Grid Specification:

The DataGrid binds to the Customers property. Sorting happens on the client-side via CollectionViewSource.

「なるほど、CollectionViewSourceを使っているのか」

僕はその情報を信じて、ViewModel内のCollectionViewSourceの設定を探し始めました。しかし、どこにも見当たらない。コードをgrepしても出てこない。

1時間ほど彷徨った挙句、実際のXAMLとC#コードを追って判明したのは、パフォーマンス改善のために、3ヶ月前にサーバーサイドページング（バックエンドでのソート）にロジックが書き換えられていたという事実でした。

仕様書は更新されていなかったのです。

隠れたコストその２：嘘のドキュメントによる調査時間の増大

ドキュメントは「書いた瞬間」から劣化が始まります。コードは常に真実を語りますが、ドキュメントはメンテナンスされなければ「嘘」になります。

「完全なドキュメント」を目指したが故に、更新が追いつかず、結果として「立派な嘘」が大量生産されていたのです。僕は仕様書を信じたせいで、無駄な1時間を過ごしました。最初からコードだけを読んでいれば、10分で解決していたはずです。

「レビュー」という名の儀式

開発プロセスにおける最大のボトルネックは、「コードレビュー」ではなく「ドキュメントレビュー」になっていました。

新しい機能を追加する際の流れはこうです。

  1. ドキュメントを書く（設計書、I/F仕様書）。
  2. ドキュメントのレビュー会を開く（2時間）。
  3. ドキュメントの修正と再承認。
  4. ようやくコーディング。
  5. コードレビュー。
  6. 実装とドキュメントの整合性チェック。

特に辛かったのが「2. ドキュメントのレビュー会」です。

多国籍チームあるあるですが、英語のニュアンスについての議論が始まってしまうのです。

「この『Should』は『Must』にすべきではないか？」

「この受動態の表現はわかりにくい」

私たちはソフトウェアを作っているはずなのに、いつの間にか「英語の教科書」を作っているような錯覚に陥りました。コードのロジックやアーキテクチャの妥当性よりも、「ドキュメントの体裁」に膨大なエネルギーが注がれている。

機能実装自体は3日で終わるものが、このプロセスのせいで2週間かかる。これが「進まないプロジェクト」の正体でした。

リファクタリングへの恐怖と技術的負債

そして、最も恐ろしい副作用が**「Stagnation（停滞）」**です。

ある日、僕はViewModelの中に、明らかに重複しているロジックを見つけました。

「これを基底クラスに抽出して、共通化（リファクタリング）すれば、コードが半分になって見通しが良くなるな」

エンジニアとしての本能がそう囁きます。しかし、次の瞬間、脳裏によぎったのはDaveの顔と、分厚いWordファイルでした。

「待てよ。このコードを直すということは、関連するクラス図、シーケンス図、そして各画面の詳細設計書の記述もすべて書き直さなきゃいけないのか……」

修正対象のドキュメントは、ざっと見積もっても30ページ。

僕はそっとVisual Studioのエディタを閉じました。

「……見なかったことにしよう」

隠れたコストその３：コード品質の維持放棄

ドキュメントが重すぎると、エンジニアはコードを触ることを恐れるようになります。「コードを良くする作業」に対するペナルティ（ドキュメント修正コスト）が高すぎるからです。

結果として、コードは汚いまま放置され、技術的負債は雪だるま式に膨らんでいきました。「完全なドキュメント」を守るために、肝心の「プロダクトの品質」が犠牲になったのです。これは本末転倒という他ありません。

決定的な事件：緊急パッチのパラドックス

「承」のクライマックスとなる事件が起きます。リリース直前のUAT（ユーザー受入テスト）フェーズでのことです。

重要な計算ロジックにバグが見つかりました。特定の通貨換算において、端数処理が誤っており、請求金額が1セントずれるという、金融系システムとしては致命的なバグです。

顧客は激怒しており、「明日までに修正パッチを出せ！」と要求してきました。

原因はすぐに判明しました。decimal型の丸め処理のモード指定ミスです。修正は1行。テストコードを含めても15分の作業です。

僕はすぐに修正コードを書き、プルリクエストを作成しました。しかし、QA（品質保証）マネージャーがそれを拒否（Reject）したのです。

「ドキュメントが更新されていない。プロセス違反だ」

僕は耳を疑いました。

「緊急事態だぞ！ 先にFixをデプロイして、ドキュメントは後追いで更新すればいいじゃないか」

と僕は食い下がりました。しかし、マネージャーは首を横に振ります。

「いいや、ルールはルールだ。ドキュメントとコードの乖離は許されない。それがDaveの方針であり、我々の品質基準だ」

その夜、僕はバグそのものの修正ではなく、Wordファイルの「改訂履歴」を埋め、計算式の説明文を修正し、PDFに出力して承認フローを回す作業に4時間を費やしました。

その間、バグを含んだシステムは稼働し続け、誤った請求書が発行され続けました。

夜中の3時、オフィスの静寂の中で、僕は承認ボタンが押されるのを待ちながら思いました。

「このドキュメントは、一体誰を守っているんだ？ 顧客か？ プロジェクトか？ それとも、誰かの保身か？」

答えは明らかでした。この過剰なドキュメント主義は、責任の所在を曖昧にするための巨大な緩衝材であり、実質的な価値を生むどころか、顧客に損害を与えていたのです。

この「緊急パッチ事件」を境に、チーム内の雰囲気は最悪のものになりました。

「俺たちは何のために働いているんだ？」

そんな無力感が蔓延する中、プロジェクトはいよいよデッドラインを迎えます。しかし、積み上がったドキュメントと、メンテナンスされずに腐り始めたコードの乖離は、もはや修復不可能なレベルに達していました。

次回の「転」では、この閉塞した状況がどのように打破されたのか。あるいは、どのように破綻したのか。

そして、そこから得られた「本当に必要なドキュメントとは何か」という気付きについてお話しします。

キーワードは**「Living Documentation（生きたドキュメント）」と「Code as Documentation」**。

地獄の底で僕たちが見つけた、一筋の光の話です。

地下組織としての「ドキュメント改革」

～The hidden costs of over-documentation: time, morale, and stagnation～

限界点と「地下活動」の始まり

「承」でお話しした「緊急パッチ事件」の後、チームの空気は完全に死んでいました。

優秀なハンガリー人エンジニアのピーターは、ついにこう言いました。

「来週、辞表を出すつもりだ。俺はエンジニアだ。小説家になりに来たんじゃない」

僕も同じ気持ちでした。でも、悔しかった。技術的には解決できる能力があるのに、プロセスに殺されるなんて。

そこで僕は、ピーターをランチに誘い、ある提案をしました。

「辞める前に、最後にもう一度だけ賭けをしないか？ Dave（リードアーキテクト）には内緒で、僕たちのやり方で開発を進めるんだ。結果が出なければ、その時こそ一緒に辞めよう」

ピーターはニヤリと笑い、グラスを掲げました。「Guerrilla Engineering（ゲリラ・エンジニアリング）だな。乗った」

その日から、僕たちの秘密のプロジェクト、名付けて**「Project: Living Doc」**が始まりました。

武器その１：XMLコメントとDocFXの導入

最初に着手したのは、「仕様書とコードの二重管理」をぶっ壊すことでした。

C#には強力な機能があります。/// (トリプルスラッシュ) で記述する XML Documentation Comments です。

僕たちは、Wordの仕様書を更新するのを（勝手に）やめました。その代わり、すべてのクラス、すべてのパブリックメソッド、プロパティに、英語で簡潔かつ正確なコメントを書き込みました。

C#

/// <summary>
/// Calculates the final billing amount applying current exchange rates.
/// </summary>
/// <remarks>
/// Note: The rounding strategy uses MidpointRounding.AwayFromZero to comply with legal requirements.
/// See ticket JIRA-1234 for details.
/// </remarks>
public decimal CalculateTotal(decimal amount, string currencyCode) { ... }

そして、ここからが重要です。僕は夜なべしてCI/CDパイプライン（Azure DevOps）をいじり、「DocFX」 というツールを組み込みました。

これは、ソースコード内のコメントを解析し、静的なHTMLドキュメントサイトを自動生成するツールです。

コードをコミットするたびに、サーバー上でドキュメントサイトが自動更新される。

つまり、「コードを書くこと」がそのまま「ドキュメントを更新すること」になったのです。

武器その２：WPFにおける「Design-Time Data」

WPF/XAML特有の「画面仕様書のスクショ地獄」に対する回答も用意しました。

それは、Design-Time Data (d:DataContext) の徹底活用です。

これまでは、Wordに「この画面にはこういうデータが表示される」と文章とスクショで説明していました。

しかし、僕たちはXAMLの中に、デザイナー画面でのみ有効なダミーデータを直接記述するようにしました。

XML

<UserControl ...
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    d:DataContext="{d:DesignInstance Type=vm:CustomerViewModel, IsDesignTimeCreatable=True}">

これにより、Visual Studioのプレビュー画面を見るだけで、「どんなデータが、どう表示されるか」が一目瞭然になりました。

「仕様書を見て想像する」のではなく、「XAMLデザイナーを開けば、そこが動く仕様書になっている」。

これが、UI仕様書のメンテナンスコストをゼロにした瞬間でした。

武器その３：ユニットテストを「仕様書」にする

ロジックの複雑な仕様については、「Fluent Assertions」 を使った読みやすいユニットテストを大量に投下しました。

従来のドキュメント：

「ユーザーが未成年の場合、割引率は0%であるべきである」

僕たちが書いたテストコード：

C#

[Test]
public void Should_Have_Zero_Discount_When_User_Is_Underage()
{
    // Arrange
    var user = new User { Age = 17 };
    
    // Act & Assert
    user.CalculateDiscount().Should().Be(0);
}

メソッド名を英語の文章のように書くことで、テスト一覧がそのまま「仕様一覧」になります。

そして何より素晴らしいのは、「仕様（テスト）が間違っていれば、ビルドが失敗する」 ということ。

Wordドキュメントは嘘をつきますが、コンパイラとテストランナーは嘘をつきません。これが「Executionable Specification（実行可能な仕様書）」です。

審判の日：Daveとの対決

3週間後、その日はやってきました。スプリントレビューの場で、Daveが顔をしかめました。

「おい、SharePointの仕様書フォルダ、最終更新日が3週間前になっているぞ。どういうことだ？」

会議室の空気が凍りつきます。ピーターが僕を見ました。僕は頷き、プロジェクターのケーブルを自分のPCに繋ぎました。

「Dave、仕様書ならここにあります」

画面に映し出されたのは、Wordファイルではなく、DocFXで生成された美しく整理されたWebサイトでした。

左側のナビゲーションから「BillingService」をクリックすると、最新のAPI定義、そしてremarksに書かれた「なぜそのロジックなのか」という意図が表示されます。

さらに、別のタブを開き、テストレポート画面を見せました。緑色のチェックマークが並び、ビジネスルールがすべて網羅されています。

「Dave、Wordファイルは死んだ情報です。でもこれは生きています（Living）。今のコードの状態を100%正確に反映しています。我々がメンテナンスすべきなのは、Wordの体裁ではなく、このコードとコメントです」

Daveはしばらく画面を凝視していました。数分間の沈黙。僕の心臓は早鐘を打っていました。クビか、採用か。

やがて、彼はゆっくりと眼鏡を外し、こう言いました。

「……検索機能はあるか？」

「あります。クラス名でも、機能の説明文でも、一瞬でヒットします」と僕。

「……リンク切れは？」

「ありえません。コンパイルエラーになりますから」とピーター。

Daveは深く息を吐き、そして微かに笑いました。

「我々が15年前の失敗から学ぼうとして作り上げた『完全なドキュメント』は、現代のツールセットの前ではただの足枷だったわけか……。よし、認めよう。Wordは廃止だ。今日からこれが我々の『Single Source of Truth（唯一の真実）』だ」

パラダイムシフト：「What」ではなく「Why」を書く

この「反乱」が成功した後、チームには劇的な変化が訪れました。

まず、**「ドキュメントの定義」**が変わりました。

これまでは「コードが何をしているか（What）」を書いていました。i++を見て「iをインクリメントする」と書くような無意味なものです。

しかし、これからは「コード自体」がWhatを語ります。

では、人間が書くべきドキュメント（コメント）は何か？

それは**「Why（なぜ）」**です。

  • なぜこのアルゴリズムを選んだのか？
  • なぜここで例外を握りつぶしているのか？
  • なぜ他のライブラリではなくこれを使ったのか？

コードからは読み取れない「設計の意図」や「背景」だけを記述する。これが、プロフェッショナルなドキュメントのあり方だとチーム全体が理解しました。

英語力とネーミングセンスの向上

意外な副産物もありました。日本人の僕にとって、これは大きな収穫でした。

「コードそのものをドキュメントにする」ためには、変数名やメソッド名が極めて明瞭な英語でなければなりません。

var d = Getdata();

なんてコードは許されません。

var activeUserSubscriptions = subscriptionRepository.FetchActiveByUserId(userId);

と書く必要があります。

チーム内で「ネーミングレビュー」が活発になりました。

「この名前だと誤解を招く」「もっと適切な動詞はないか？」

文法的な正しさよりも、意図が伝わるかどうか。結果として、僕たちの英語力（特にエンジニアリング英語）は飛躍的に向上しました。

転の終わりに：自由を取り戻したエンジニアたち

Wordファイルの更新作業から解放されたエンジニアたちは、水を得た魚のようでした。

リファクタリングへの恐怖もなくなり、コードベースは日に日にクリーンになっていきました。

あの「変更への恐怖」が支配していた現場は、今や「変更を歓迎する」アジャイルなチームへと生まれ変わったのです。

しかし、物語はここで「めでたしめでたし」では終わりません。

この変革を通じて、僕は「海外で働くエンジニア」として、もっと根本的な、ある一つの真理にたどり着きます。

それは、技術やツールを超えた、エンジニアとしての「生き様」に関わることでした。

最終章「結」では、この経験から得られた「海外でサバイブするための5つの教訓」と、これを読んでいるあなたが明日から実践できる具体的なアクションプランについてお話しします。

完璧主義を捨て、実用主義の荒野へ

～The hidden costs of over-documentation: time, morale, and stagnation～

プロジェクトのその後：Daveの変心

あの「反乱」から半年後。僕たちのプロジェクトは無事にカットオーバー（リリース）を迎えました。

以前のようなデスマーチはありませんでした。バグが出ても、テストコードが即座に場所を特定し、修正は数時間で完了し、ドキュメント（という名の自動生成サイト）は常に最新の状態でした。

打ち上げの席で、ビールを片手にDaveが僕の肩を叩きました。

「正直に言おう。最初は君たちのやり方に恐怖を感じたよ。テキストがないことに不安だった。でも、今はわかる。『信頼』は紙の上ではなく、動くコードの中に宿るんだとな」

あの堅物だったDaveが、今では他のプロジェクトチームに「DocFXとユニットテストの導入」を説いて回っているそうです。人は変われる。結果さえ示せば。

この経験は、僕のエンジニア人生における最大の教訓となりました。それは単なるツールの話ではありません。「エンジニアとしてどう生きるか」という哲学の話です。

ここからは、僕が実体験から抽出した、あなたが海外（そして日本でも）で生き残るための「5つの生存法則」をシェアします。

法則1：日本の「完璧主義」をアップデートせよ

私たち日本人エンジニアには、素晴らしい美徳があります。「勤勉さ」と「細部へのこだわり」です。しかし、これがドキュメント作成においては仇（あだ）になることがあります。

日本では「言質を取られないように」「念のために」すべてを網羅しようとします。これは「減点方式」の文化への適応です。

しかし、海外の、特にアジャイルな現場では「加点方式」です。「どれだけ完璧な資料を作ったか」ではなく、「どれだけ早く価値（動く機能）を届けたか」が評価されます。

アドバイス：

「100点のドキュメント」を目指すのをやめてください。それは誰にも読まれません。

目指すべきは**「Just Enough（ちょうどいい）」**です。

チームが次に進むために必要な、最低限の情報だけを残す。不安だから書くのではなく、必要だから書く。この「捨てる勇気」が、あなたの時間を守ります。

法則2：「What」ではなく「Why」だけを書け

もし明日からドキュメントを書く（あるいはコードにコメントを書く）必要があるなら、このルールだけを守ってください。

  • Bad: コードを見ればわかること（What/How）を書く。
    • 例：「ループでリストを回して合計を出す」
  • Good: コードからは読み取れない「意図（Why）」を書く。
    • 例：「パフォーマンス要件によりLINQではなくforループを使用（チケット#123参照）」

ドキュメントの役割は、**「コードという地図に載っていない『歴史的背景』や『落とし穴』を記すこと」**です。

「なぜ、あえてこの汚いハックをしているのか？」

「なぜ、このビジネスルールはこんなに奇妙なのか？」

これこそが、後任のエンジニアが喉から手が出るほど欲しい情報です。

法則3：英語力が低いなら、コードを「雄弁」にしろ

海外で働くにあたり、英語の壁は必ずあります。僕もネイティブのように流暢な文章は書けません。だからこそ、戦略を変えました。

「英語の説明文を書かなくて済むように、コード自体を英語の文章にする」

変数名、メソッド名を極限まで具体的にするのです。

  • var f = false; // 謎のフラグ
  • var isEligibleForDiscount = false; // 誰が見てもわかる

これを徹底すると、不思議なことが起きます。

「お前のコードは読みやすい。英語が上手いな」と褒められるのです。実際には、僕は難しい文法を使わず、ただ適切な単語を選んで並べただけです。

コードは世界共通言語です。**「Self-Documenting Code（自己文書化コード）」**こそが、ノンネイティブ・エンジニア最強の武器です。

法則4：自動化できないルールは、いつか破綻する

「手動でスクショを撮ってWordに貼る」

「Excelの設計書とソースコードを突き合わせてチェックする」

人間の「頑張り」や「注意力」に依存したプロセスは、必ず失敗します。特に海外では、メンバーの入れ替わりが激しい。新しい人が入るたびにルールを教え込むのは不可能です。

解決策：

**「プロセスをツールに落とし込む」**こと。

WPFならDesign-Time Data、APIならSwagger、アーキテクチャなら単体テストでの制約チェック（ArchUnitなど）。

「人間が意識しなくても、勝手にドキュメントが生成される」「ルールを守らないとビルドが通らない」仕組みを作る。これが、エンジニアリングによる解決です。

法則5：ドキュメントは「信頼」の代替品である

これが最も深い気づきでした。

なぜDaveはあんなに大量のドキュメントを求めたのか？ それは、チームやコードを「信用していなかった」からです。

「ちゃんと作っているか不安だから、証拠（ドキュメント）を出せ」と言っていたのです。

しかし、僕たちが動くコード、通るテスト、そして常に最新の自動生成ドキュメントを見せ続けたことで、その「不信」は解消されました。信頼が構築されると、過剰なドキュメントは不要になります。

「君たちが大丈夫だと言うなら、大丈夫だろう」

この言葉を引き出すことこそが、プロフェッショナルのゴールです。

最後に：あなたへのメッセージ

今、あなたの目の前には、更新が滞った仕様書や、誰も読まないWikiがあるかもしれません。

それを見て、「自分はなんてダメなんだ」「ちゃんと更新しなきゃ」と自分を責めないでください。

悪いのはあなたではなく、「More is Better（多ければ多いほど良い）」という古い幻想です。

エンジニアであるあなたの手は、Wordでフォントサイズを調整するためにあるのではありません。

世界を変えるコードを書き、ユーザーの課題を解決するためにあるのです。

明日、出社したら（あるいはZoomに入ったら）、小さなことから始めてみてください。

無意味なコメントを一行消すこと。

メソッド名をわかりやすくリネームすること。

Wordに書く代わりに、コードの中に/// <summary>を書くこと。

その小さな「反乱」の積み重ねが、やがてあなたとチームを、あのドキュメント地獄から救い出し、本来のクリエイティブな世界へと連れ戻してくれるはずです。

The Documentation Dilemmaからの脱出。

鍵は、いつだってあなたの指先にあります。

コメント

タイトルとURLをコピーしました