ドキュメントは最強のコミュニケーションツールである――Joelの機能仕様書入門：プロジェクト成功確率向上の近道とは？（1）（2/2 ページ）

[寺田英雄，株式会社オープンストリーム CTO]

Joelの機能仕様書とは

　有名なソフトウェア技術ブログ『ジョエル・オン・ソフトウェア（Joel on Software）』の著者であり、元マイクロソフトのエンジニアであるジョエル・スポルスキ氏が紹介している仕様書の書き方が、Joelの機能仕様書です（スポルスキ氏本人は、単に「機能仕様書（functional specifications）」と呼んでいます。ここでは、一般的な仕様書と区別するために、この名前を使っています）。

Joel on Software

　Joelの機能仕様書とは、ひと言で表すと「そのソフトウェアがどのように機能するのかを、ユーザー観点で読みやすくまとめたドキュメントであり、設計者とユーザー（顧客）が仕様を共有し、コミュニケーションするための道具となることを狙った仕様書」です。

　Joelの機能仕様書の詳しい書き方は、氏の著書やWebサイト（有志による日本語版）にも無償公開されていますが、最初に公開されてから10年以上経つため、最近では知らない人も多いようです。

有志による日本語版

　しかし、その内容と意義は今でも輝きを失わない素晴らしいものなので、今回再度紹介しました。ただ、そのスタイルは米国流の文化の影響を受けている面があるので（例：ジョークを多用しようとする所など）、そのままではわれわれ日本人にはなじみにくい部分もあります。今回は、それらを筆者流にアレンジしたスタイルで紹介してみようと思います。

Joelの機能仕様書の3つの役割

　スポルスキ氏流の機能仕様書の具体的な書き方の話に進む前に、この仕様書の役割を説明しておきます。そうでないと、なぜこのようなスタイルで仕様書を作るのか理解しにくくなるためです。

　スポルスキ氏のオリジナル文章では、独特の味のある文体で機能仕様書の役割を説明していますが、その分ちょっと冗長でもあるので要約してみましょう。Joelの機能仕様書には、以下の3つの役割があります。

1. エンジニアがプログラムを正しく設計（デザイン）する助けとなる
   • 設計の共有・見直しや修正が非常に簡単にでき、結果的に開発期間の短縮になる
   • 決定事項と、未決定事項を明確にする
2. コミュニケーションにかかる時間を節約する
3. スケジュールを立てるための基本情報となる

役割【1】エンジニアがプログラムを正しく設計する助けとなる

• 場当たり的な開発のリスク

　プログラマーはコードをいじくるのが大好きな人が多いと思います（筆者も、その一人です）。新しいプロジェクトを始めるとき、ざっくりと要求を理解した段階でいきなりコードを書いてしまう人が少なからず存在します。ひどい場合には、「何もまだ思いつかないけど、取りあえず起動画面だけ作ってみるか」という人もいます。

　その後彼が何をするかといえば、最初に書いたコードに少しずつ機能を付け加えていくのです。そうしてコードを膨らませていけば、いずれはシステムが完成するだろうというわけです。

　作業が進むにつれ、いろいろな設計上の問題や仕様の矛盾が出てきますが、それは、その場その場で考えてやり過ごそうとします。あるいは、「この要件には矛盾がある！ こんなの作れない」といって怒り出すかもしれません（最初によく考えずに作業を始めた自分のことを棚に上げていることに気付く人は少ないようです）。全体を見通して考慮しなければならない問題に対しては、お手上げになることさえあります。

　また、このようにして膨らませただけのコードも、簡単に捨て去ることができなくなっていることが多いと思います。プロジェクト開始からそれなりの時間が経っていれば、時間的にも心情的にも、もう後戻りできないからです。

　このような“場当たり的”なプログラミングがリスキーなのは明白です。機能仕様書を書かずにいきなりコーディングに入れば、次に述べる例のように、開発期間が長引くのは間違いないですし、下手をすると完成しないかもしれません。

• 場当たり的開発は時間の浪費である

　機能仕様書では、自然言語（私達日本人なら日本語）で仕様の要点を書いていきます。例えば、スマートフォン用にカメラを使ったアプリケーションを開発しているとしましょう。以下のような仕様を記述したとします。

（1）カメラを起動してユーザーに写真を撮影してもらう。撮影したら、その画像を左右反転し、横1024ピクセルに縮小してからファイルに保存する。

　今、筆者がこの仕様を書くのにほんの1分もかかりませんでした。これを見たユーザーから以下のような指摘を受けたとしても、修正するのは数分程度でしょう。

ユーザー指摘

ユーザーが撮影した写真の横幅が1024ピクセル未満のときはどうするのですか？

修正版仕様書

（1）カメラを起動してユーザーに写真を撮影してもらう。撮影したら、その画像Aを左右反転し横1024ピクセルに縮小してからファイルに保存する。ただし、オリジナルの画像Aの横幅が1024ピクセル未満の場合は、警告メッセージを出し、もう一度カメラに戻して1024ピクセル以上の画像をユーザーに撮影してもらうようにする。

　逆に、もしこのような仕様書を作らずに「ベータ版」のアプリを作ってしまったとしましょう。最初のバージョンを作るのに数日はかかるでしょう。そして「ベータ版」を見たユーザーから上記のような指摘を受け、そこからプログラムの修正に入ると、画面遷移の変更に1日かかることが判明しました。さらに他の機能やデータ構造の変更などの兼ね合いから、追加の修正作業やテストに数日必要になりそうです。

　結果的に、最初に機能仕様書を書いていれば数分で終わったはずの作業に数日を要しているのです。これは完全に時間の無駄使いです。

• 機能仕様書によって正しい設計に速く到達できる

　前記の例のように、機能仕様書を書くメリットは設計に要する時間の節約です。仕様書に書けば、それぞれの機能はほんの数行の日本語となり、誰が読んでも理解できるものとなります。修正も簡単です（ビルドエラーも出ません！）。いきなりプログラムコードを書いてしまうと、その何倍も時間がかかります。しかもプログラマーにしか理解できませんし、修正もはるかに困難です。

　また、機能仕様書なら問題点を早期に発見できます。そもそも要求を正しく理解していなければ仕様が書けないので、プログラマー（設計者）自身の理解度を試す良いテストになります。そして、ユーザーを含めた多くの人にレビューを受けることができ、間違いや不足点を速く洗い出せます。

• 機能仕様書によって未決定事項がはっきりする

　たいていのシステムには、ユーザーの間でも意見が割れる“デリケートな”機能があります。その仕様はなかなか決まらず、何回ミーティングしてもペンディングのままになることも多いでしょう。ドキュメントを軽視するチームが開発すると、この種の問題は途中でうやむやになることがしばしばあります。そして、納期直前になって「そういえば、あの件はどうなった」という指摘を受けて大問題になるのです。

　仕様書に慣れているチームならば、このような問題は未然に防げます。仕様書に「この仕様は未定である（TBD：To Be Determined）」という印を付けて記載できるからです。仕様書は決定事項を書くためだけのものではなく、未決事項や検討中の事項も記載して構わないのです。

役割【2】コミュニケーションにかかる時間を節約する

　仕様書は一度書いてしまえば、どんなに多くの人と共有してもコストは同じです。ユーザーもテストチームも、サポートチームも営業も同じものを読むことができ、同じ出発点に立ってシステムを理解できるようになります。後からチームに加わった人に、ゼロから同じ話をする必要もなくなります。また、設計者自身も何度も何度も読み返して確認できます。

　もし仕様書がなかったとしら、悲惨な状態になるでしょう。開発メンバーはもとより、テストやサポートのチームからも何か仕様に疑問が生じるたびに開発チームに質問が飛んできます。それも同じような質問が何度も何度も来ます。そのたびに開発作業に割り込みが生じ、一番貴重な開発チームの生産性が下がるのです。これは表面的には目に見えないですが、大きなコストとしてのし掛かってくるでしょう。

役割【3】スケジュールを立てるための基本情報となる

　プロジェクト計画に当たって、自分たちがどんなシステムを開発すればいいのか正確に理解できていなければ、スケジュールも正確に見積もれません。仕様書によって機能が明確になってこそ、正確に作業項目を洗い出すことができ、正確なスケジューリングにつながるのです。

まとめ：仕様書を書くことは生産性向上に役立つ

　今回は、連載第1回として、ITシステム開発におけるコミュニケーションの重要性、そしてコミュニケーションにおけるドキュメントの重要性について説明しました。

　そして、筆者が特に重要と思う3つのドキュメントのうち、一つ目の「Joelの機能仕様書」について概要と役割を説明しました。仕様書を書くことがいかに生産性向上に役立つか再認識していただけたかと思います。

次回は、「Joelの機能仕様書」についての具体的なテクニック

　次回は、「Joelの機能仕様書」について具体的な書き方や作文のテクニック、作成時に使うと便利なツールなどについて説明していきます。

「プロジェクト成功確率向上の近道とは？」バックナンバー

• 残業も減らせる!? 上級エンジニアになるためのDesign Doc超入門
• サンプル例に見る機能仕様書の基本的な書き方＆読みやすくする7つのテクニック
• ドキュメントは最強のコミュニケーションツールである――Joelの機能仕様書入門

著者プロフィール

寺田英雄

株式会社オープンストリーム CTO

1990年代から制御・FA系の画像認識、動画処理を中心としたソフトウェア開発に携わってきた。

2007年からはインターネットIT系に転身、モバイル系開発などを経て、2012年にオープンストリーム入社。

現在は数理アルゴリズムや機械学習・AIを応用した次世代の計算機システムに挑戦している。

『理論と現場の融合、知恵と勇気の開発』がモットー。