開発者が実際に読む仕様書の書き方

入れるものと入れないもの

画素の一つひとつまで書いた仕様書は、二週間後には誰も更新しない文書になります。構想だけを書いた仕様書は、一日に二十の質問を生みます。その中間にある答えは、機能ごとに、誰が使い、通常の流れで何が起き、失敗したとき何が起き、どの条件を満たせば完了と見なすかを書くことです。

受け入れ条件が、議論の大半を減らしてくれます。「利用者は一分以内に通知を受け取る」は条件であり、「処理は速くする」は願望です。

画面ではなく、流れを書く

流れを順序として書きます。開始状態、操作、結果。そのうえで失敗経路を書きます。通信できない、途中で閉じた、ファイルが壊れている、権限がない。実際のプロジェクトでは、失敗経路が作業量の半分を占め、仕様書の四分の一を占めます。

画面は作り直されますが、流れは残ります。だからデザインは仕様書に埋め込まず、リンクで結びます。

誰もが飛ばす部分

このバージョンの範囲外を明示的に書きます。「今回はやらない」の一覧は言い訳ではなく管理の道具です。会議のたびに議論をやり直す代わりに、「その通り、それは次です」と言えるようになります。

前提も書き添えます。書かれた前提は管理された危険であり、頭の中にとどまった前提は不意打ちになります。