サンプル例に見る機能仕様書の基本的な書き方＆読みやすくする7つのテクニック：プロジェクト成功確率向上の近道とは？（2）（1/3 ページ）

ITシステム開発の問題点の一つであるコミュニケーションの失敗。本連載では、これを防ぐ方法としてお勧めしたい3つのドキュメントを紹介していく。今回は、Joelの機能仕様書を日本人向けにカスタマイズされたものを例に、機能仕様書の基本的な書き方、読みやすくする7つのテクニック、仕様書作成ツールは何を使うべきか、誰が書くべきかなども解説します。

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

連載目次

　連載の第1回の前回「ドキュメントは最強のコミュニケーションツールである――Joelの機能仕様書入門」では、ITシステム開発がビジネスに貢献していくためには、まずは開発の成功が出発点になること、そしてITシステム開発におけるコミュニケーションの重要性、そしてコミュニケーションにおけるドキュメントの重要性について説明しました。

　そして、重要な3種類のドキュメント『Joelの機能仕様書』『Design Doc』『議事録』を挙げ、まず1種類目として『Joelの機能仕様書』について概要を説明しました。今回は具体的にJoelの機能仕様書の書き方を説明していきます。

あらためて『Joelの機能仕様書』とは何か？

　Joelの機能仕様書は、ユーザー視点でソフトウエアの動作や画面の仕様（＝いわゆるユーザー体験の仕様）を記述し、ユーザーと開発者とが情報共有（共通理解）をするためのドキュメントです。

　技術仕様書ではありませんので、ソフトウエア内部の構造や実装方法については、あまり記述しない方がいいでしょう（技術的な話をたくさん書いてしまうと、技術者以外の人には意味が分からなくなってしまいます）。

サンプルで分かる日本人向け機能仕様書の基本的な書き方

　機能仕様書がどんなものか、雰囲気を掴んでいただくため、まずはサンプルPDFを見ていただきましょう。このサンプルは、ジョエル・スポルスキ氏のオリジナル版を筆者が日本人向けに少し修正したものです。以下では、このサンプルの構成に沿って機能仕様書の書き方を説明していきます。

サンプルPDF

『目次』

　目安としてA4で10ページを超えるような仕様書には目次があった方がいいでしょう。仕様書作成に使っているツールで自動的に作成できる場合は、迷わず入れておいた方がいいと思います。

『はじめに』

　この仕様書の読者に対して、仕様書の位置付けや読み進める上で注意してほしいことなどを書きます。

　スポルスキ氏のサンプルでは、『この仕様書は不完全である』として、仕様書は生き物であり、今後も常に更新され続けることを注意喚起しています。これはうまいやり方だと思います。文書は一度作成すると『一人歩き』してしまうことがあります。作られた背景や流れを理解していない人が文書を目にしてしまい、主旨を誤解されるかもしれません（例：『あの仕様書は、もう完成したんじゃなかったの？』）。こうした注意書きを入れておくのは保険として有効でしょう。

　その他、このシステムの狙いや開発に対する思い、開発チームへのメッセージなどを記述してもいいと思います。

『シナリオ』

　このシステムの使い勝手がどのようなものになるのか、ユーザー目線でシナリオ（ストーリー）として記述します。

・シナリオとは？

　シナリオとは、ストーリーの展開の順序通りに、時系列的に書いた文章のことです。登場人物の動作と、それに対するシステムの反応や処理結果などを順を追って書いていきましょう。

・シナリオの書き方

　読者に誤解を与えないよう、できるだけ具体的に利用場面を想像しやすいように書きましょう。登場人物や場所などには具体的な名前を付け、どんな個性を持った人なのかも表現できると分かりやすくなります。

　内容が多くて一つのシナリオでは描ききれない場合は、複数に分けましょう。機能単位で分割する、画面単位で分割するなど、システムの特徴に応じて適切な分割方法があると思います。

　以下の例のように、ユーザーとシステムの動作だけではなく、その動機も併せて記述できればより理解が深まります。

例：ユーザーの動機を含んだシナリオ記述

テンプレート

＜ユーザーA＞は、＜機能X＞を使って＜動作Y＞を行う。なぜなら＜ユーザーA＞は＜目的Z＞を行いたいからだ。

例

佐藤社長は、定時近くになるとWhatTimeIsIt.comの時刻表示機能を使って、現在時刻の確認を頻繁に行う。なぜなら、彼は定時になったら即座に会社を出たいからである。

別案

佐藤社長は、定時近くになるとWhatTimeIsIt.comの時刻表示機能を使って、現在時刻の確認を頻繁に行う（理由：彼は定時になったら即座に会社を出たいから）。

『対象外』（または範囲外）

　開発の対象外であるものを明記します。これは、ある意味で最重要項目かもしれません。

　プロジェクトの途中で、仕様書に書かれていない機能が見つかったとき、その解釈の可能性は、（1）『書き忘れていただけで、本来実装すべき機能ですよね』と、（2）『書かれていないものは、当然実装するはずのない機能ですよね』との、2つになると思われますが、ほとんどの場合、ここで意見の相違が発生して揉めることになります。（ユーザーサイドは（1）派、開発サイドは（2）派になるのは容易に想像がつきます。）

　こうした揉めごとのリスクを下げるためにも、やらないと決めた項目はどんどん『対象外』として明記していきましょう。書く場所は、できるだけ目につきやすい場所、仕様書のなるべく前の方にするといいでしょう。

『概略フローチャート』（または概要）

　この後に続く詳細項目となる、システム機能の全体像を説明します。このサンプルではフローチャートの形式にしていますが、全体像を表現できるものであれば、他の形式でも構いません。

　シナリオでは個々の場面ごとのシステムの機能を記述しましたが、それらの機能群が全体としてどうつながっているのかがイメージできるものがいいと思います。よくあるのは、フローチャートや画面遷移図、業務フロー図、ユースケース図、機能一覧表などです。

　もちろん、文章だけで説明できるならそれでも構いません。あくまでも、ユーザー視点で分かりやすいかどうかが判断基準です。

『画面ごとの仕様』（または詳細）

　『概要』の章で説明した全体像と対比する形で、システムに含まれる要素を個別に説明していきます。機能仕様書で最も重要な部分です。

　概要で示されている範囲について、漏れなく記述することが大切です。そのためには、適切な大きさで項目を区切っていくといいでしょう。

　このサンプルでは、画面単位のフローチャートとして概要を示していたので、詳細説明も『画面ごと』になっています。画面は物理的に実在し、区切る単位として分かりやすいので漏れが出にくい方法です。

　その他の分割方法としては、機能単位で区切る方法や、データや信号の入出力の単位で区切る方法などがあります。

・区切った詳細項目に名前を付ける

　詳細項目を区切ったら、それらに名前を付けます。

　これにより、誰もが誤解なく一目で項目を認識できるようになります。◯◯画面や、◇◇機能、△△ファイルなど、具体的で短めの名前がいいでしょう。

　このサンプルでは画面に名前を付け、さらにそれに下線を付けることで、それが画面名であることを強調して表現しています。仕様書の読みやすさを高める工夫です。

・機能を詳細に記述する

　システムがユーザーに提供する機能を一つ一つ、詳細に記述します。

　基本的な機能から始まって、補助的な機能、画面の動き、出力されるデータやファイル、そしてエラーや異常の発生時の動作などを記述していきます。必要に応じてサブ項目を設けてもいいでしょう。

　ここでも、説明時の視点はユーザーです。ユーザーから見てシステムがどのように振る舞うのかを説明していきましょう。

　この詳細説明はシステムの実装仕様につながる出発点として重要です。実装やテストの作業中に、各機能の意味や目的を確認するため、エンジニアは何度もこの項目を見返して確認することになるからです。

　このサンプルでは、ログインフォームの項でユーザーが入力する項目にエラーがあった場合の振る舞いについて詳細に説明しています。

『未解決の問題』（またはTBD）

　今すぐには解決・決定できない事柄について、その都度記述します。

　システムの機能を設計していく過程で、すぐには決定できない課題が出てくることはよくあります。その場合は、『後で決定してからまとめて書く』のではなく、課題があることに気付いた時点でそのこと書いておきましょう。漏れや抜けが起きる可能性を小さくできます。

　未解決問題は、このサンプルのように独立した見出しを付けた項目としたり、特別な目印を付けて後で見つけ出しやすくしておきます。ちなみに筆者は、「TBD」という記号をよく使います。TBDは「To Be Determined」（後で決定する）の略です。決まった記号を使うことで、後で仕様書内の未解決項目を検索するのが楽になります。

『技術メモ』（または特定用途メモ）

　特定の読者層向けの注意事項を記述します。

　機能仕様書を書く人は技術系の出身者が多いと思います（この点については『誰が機能仕様書を書くのか』の章で後述します）。機能仕様書はユーザー視点で書かなければなりませんが、書いている途中で技術的な課題や解決策のアイデアなどが頭に浮かぶこともあります。そうしたアイデアを忘れてしまうのはもったいないので、『技術メモ』というサブ項目や脚注などを作成して、要点を記述してしまいましょう。

　後ほどプログラマーにとって貴重なヒントになる可能性がありますし、項目を分けておくことで技術に興味のない人は読み飛ばすことができます。

　同様に、テストに関するメモは『テスト・メモ』、セキュリティに関するメモは『セキュリティ・メモ』、取り扱い説明書に加えてほしい事項があれば『ドキュメンテーション・メモ』などといった項目を設けて記述しておきましょう。