寓話
設計図のない水車は、一度直してもまた壊れる
渓谷に水車が一架あり、最初は老匠人が自らの手で組み上げた。それは製粉所を動かし、田畑を灌漑し、染め工房に水を送った。老匠人は各木軸の癖を知っていたが、ほとんど書き残さなかった。
水車が引き受ける仕事はますます増え、隣には暗渠、分水閘、夜間警鈴が加わった。新しい徒弟は老匠の手振りを真似るだけで、水がどこから来て、どこを通り、いつ止まるかを完全に理解する者はいなかった。
最初の故障の後、坊主は弟子に修理の心得を書かせた。心得には小技ばかりが並び、全体図、インターフェース、制約、変更履歴、緊急手順はなかった。次に別の場所が壊れたとき、その心得はほとんど役に立たなかった。
寒波が暗渠を凍結させて裂いたが、老匠人は街にいなかった。徒弟たちは水車を囲んで夜中まで議論し、最後に間違った水門を閉めてしまい、製粉所を救えず、染物工房も止まってしまった。
老匠が戻っても、弟子を責めなかった。彼は水車を幾層もの図に描いた。全体構造、各水門の責任、正常な水路、異常な水路、保守周期、変更禁止の部位である。
彼はまた、変更ごとに理由、影響範囲、テスト結果、ロールバック方法を明確に書くよう求めました。図面はもはや竣工記念ではなく、水車が動き続けるための一部です。文書も異なる読者に分けられました。徒弟は日常保守、検収官は安全境界、坊主は影響範囲、外部の職人はインターフェースと禁止区域を見ます。これらを明確に書くことで、水車は特定の誰かの記憶だけに頼らずに済むのです。
数か月後、新しい徒弟は小さな故障を独力で処理できるようになり、外部の検収官も水車が下流の田畑をどう守るかを理解できるようになった。老匠の経験はついに彼の頭から離れた。後に管事はこの経験を日々の規則に書き加えた：まず場面を見て、次に境界を見て、最後に失敗したときに誰が引き継げるかを見る。これらすべてが明確になって初めて、美しいデモは納品可能な仕事になる。
工房主は言った。技術文書は過去に向けて書くものではなく、次にこのシステムを保守し、審査し、引き継ぎ、信頼する人に向けて書くものだと。後に工房主はさらに定めた。図面は水車と一緒に更新すること。水門を変えて図を変えなければ、図がないより危険である。新しい徒弟は古い図で操作し、小さな変更を大きな事故に変える。