【ITニュース解説】I Stumbled Into Documentation-Driven Development

あるシステムエンジニアが、自身のためにPython製のコマンドラインツール「Ephem」を開発している時の話だ。彼は占星術師であり、Linuxのターミナルを日常的に使うユーザーだ。彼は自分のツールをバージョン2.0.0としてリリースするにあたり、単なる簡単な説明文（README）だけではなく、本格的なチュートリアルを作成しようと決めた。

このチュートリアルを書き始めたことで、彼は驚くべき発見をした。何週間も自動テストを繰り返していたにもかかわらず見過ごされていた、五つものユーザー体験（UX）上の問題点が、たった一晩で明らかになったのだ。彼は、ドキュメントは製品が完成してから作るものだと思い込んでいたため、この発見に戸惑いを感じた。しかし、この経験を通して「Documentation-Driven Development（DDD）、つまりドキュメント駆動開発」という考え方に出会った。これは、「ユーザーの視点から見れば、もし機能がドキュメントに記載されていなければ、その機能は存在しないも同然であり、もしドキュメントが間違っていれば、それは機能が壊れていることと同じである」という考え方だ。

彼はプロジェクト全体を通して「まずドキュメントを書き、次にコードを書く」という推奨される手順を厳密に守っていたわけではない。しかし、チュートリアルの初稿を書く過程で、自身のGitのコミット履歴を見ると、以下のような修正が行われたことがわかる。これらは全て、ドキュメントを書く中でユーザー目線に立ったことで発見された改善点だった。

一つ目の修正は、「fix now --save-config output」だ。彼のツールは、占星術の基本である場所の座標を保存できる機能を持っていた。チュートリアルでは、ユーザーが最初に設定すべき項目としてこの座標の保存方法を説明した。しかし、チュートリアルに書かれたコマンド「now --save-config -y 30 -x -80...」を実際に実行しても、期待される星の配置図（Chart of the Moment）がすぐには表示されなかった。彼はこれまで、コマンドを実行した後に改めて別のコマンド「ephem now」を実行して結果を確認する、という余計な手間を当たり前のように行っていたのだ。ドキュメントを書き、ユーザーのつもりで操作してみることで、この不便さに初めて気づき、すぐに修正した。

二つ目は、「cast: accept seconds input」という修正だ。チュートリアルでは、ツールの開発開始時点の正確な日時（時:分:秒）を使って、その時の星の配置図を計算する例が紹介されていた。しかし、初期のプログラムでは、出生証明書によく書かれているように、時と分までしか入力できなかった。チュートリアルを書く中で、より正確な「秒」まで入力できるべきだと気づき、機能を拡張した。

三つ目は、「add --list-zones global」だ。タイムゾーンの指定について説明する際、彼は当初、ユーザーに外部のウェブサイトを参照して自分のタイムゾーンを探すよう促していた。しかし、ターミナルで作業するユーザーにとって、わざわざブラウザを開いてウェブサイトを見るのは非効率的だと、チュートリアルを書く中で気づいた。そこで、ターミナル内で利用可能なタイムゾーンのリストを表示する機能を追加することで、ユーザー体験を向上させた。

四つ目は、「now/cast: print saved index」だ。ユーザーがデータベースに情報を保存する「--save」オプションを使っても、保存が成功したという即座のフィードバックがなかった。彼自身も、これまで数ヶ月間ツールを使ってきた中で、保存されたかを確かめるために別のコマンド「data view」を実行して確認していた。つまり、彼は自分自身のアプリケーションを信頼していなかったのだ。チュートリアルの中で、他のユーザーにも「このコマンドだけでは保存されたか分からないから、別のコマンドで確認してね」と書こうとしている自分に気づき、この問題の根本的な解決の必要性を感じた。保存が成功したことをすぐに確認できるように、プログラムを修正した。

最後の五つ目は、「display.month: add day of week」という修正だ。占星術では、特定の目的に適した日を選ぶことがある。例えば、結婚式に最適な日を選ぶ際に、曜日が分からないと不便だ。チュートリアルで、占星術的な視点から「最適な結婚式の日を選ぶ方法」を説明しようとした時、日時の表示に曜日が含まれていないことに気づいた。これも、実際のユースケースを想定してドキュメントを作成することで初めて発見された改善点だった。

これらの修正は全て、個々の機能が正しく動作するかをテストする「ユニットテスト」では見つけられなかった問題だ。これらは、まるで新しいユーザーになりきって、実際の利用シーンをシミュレートする「ロールプレイング」によってのみ発見された。ユニットテストは「コードが正しく動くか」をチェックするが、ドキュメントは「人間がそのコードを実際に使えるか」をチェックするという彼の気づきは、システム開発において非常に重要な視点だ。

この開発者は、このようなドキュメント駆動開発が珍しい手法だと感じていたが、実際にはいくつかの先行事例や研究が存在することがわかった。ドキュメントは一度書いて終わりではなく、コードと同じように何度も修正され、レビューされるものだという。彼は元々ジャーナリズムを学んだ経験があり、文章の推敲に慣れていたため、この「ドキュメントを書き、それに基づいてコードを修正し、さらにドキュメントを書き直す」というプロセスを直感的だと感じた。彼は、ドキュメントの修正をGitリポジトリで管理することで、文章の変更履歴を追跡し、それが結果的に彼自身の開発者としての成長にも繋がったと語る。

さらに、彼は「Docs-inspired development（ドキュメント着想開発）」という別の視点も紹介している。これは、他のプロジェクトのドキュメントを書くことが、新しいアイデアや自身のアプリケーションの改善につながるという考え方だ。彼は、1990年代に作られた古い占星術ソフトウェアのチュートリアルを作成する中で、そのツールの不満点に気づき、それが自身のEphem開発の着想源になった経験を語った。

システムエンジニアを目指すあなたも、ドキュメント駆動開発を試すことができる。新しいプロジェクトを始める必要はなく、既存のプロジェクトでも実践可能だ。

まず、単なるREADMEではなく、本格的なチュートリアルを書いてみよう。自分自身が「先生」と「生徒」の両方を演じるような感覚で、コードベースをよく知っている自分と、全く知らないエンドユーザーの視点の両方から、コードと向き合うことができる。次に、そのチュートリアルをまるで初めて使うユーザーのように、実際に手順通りに試してみよう。そうすることで、これまでは当たり前だと思っていた余計な手順や、情報が不足している箇所などに気づくことができるはずだ。

ドキュメントは一度書いて終わりではない。不完全な状態でもドキュメントを作成し、そこから問題点を見つけてコードを修正し、そして再びドキュメントを書き直すというプロセスを繰り返そう。これは、より具体的でユーザー視点に立った「ラバーダック・デバッグ」のようなものだ。最後に、普段からよく使っている誰かのプロジェクトのドキュメントを作成してみるのも良い。そうすることで、これまで当たり前のように受け入れていた不便な点や、改善できる箇所が明確になるだろう。

ドキュメント駆動開発は、開発者がユーザーの視点を深く理解し、より使いやすいソフトウェアを生み出すための強力な手法だ。コードだけでなく、そのコードを「どう使うか」という視点を持つことが、優れたシステムエンジニアへの第一歩となるだろう。