excel
仕様書の書き方で揉めない備え｜決めた事を残す場所
仕様書の書き方を調べている理由は、たいてい2つに分かれます。何をどこまで書けばよいのか分からない場合と、書いたのに後から「そういう話ではなかった」と言われた経験がある場合です。
先に結論を書きます。仕様書は、完成した文書として1回で書き上げるものではなく、決まったことを決まった場所に足していく台帳として運用するものです。書き方の型より先に、置き場所と更新の決まりを固めてください。型だけ整えても、決定がチャットや口頭に散っていれば、同じ揉め方をします。
システム・ソフトウェア開発において仕様書は不可欠ですが、その作成には知識や経験が必要です。そこで本記事では、仕様書とは何かといった基本から、記載のポイント、わかりやすい書き方の特長などを紹介します。またサンプルも提示して、書き方のポイントを解説していきます。 出典: biz.techvan.co.jp
この記事では、似た文書との違い、書く手順、必ず入れる項目、伝わる書き方と伝わらない書き方、表計算で書く場合の限界、変更が入ったときの扱い、確認の回し方、そして決定が散らない置き方までを順に扱います。
仕様書と要件定義書と設計書の違い
言葉の整理から始めます。ここが曖昧なまま書き始めると、3つの文書の内容が1つに混ざり、誰も全体を把握できない文書になります。
要件定義書は、何のために作るかと、何ができればよいかを書いた文書です。読み手は発注する側と作る側の両方で、合意の対象になります。ここに書くのは、解決したい困りごとと、達成されたと判断できる条件です。画面の細部や処理の手順は書きません。
仕様書は、何をどう振る舞わせるかを書いた文書です。読み手は主に作る側ですが、発注する側も読んで確認します。画面にどの項目があり、どの操作でどうなり、条件が満たされないときにどう振る舞うかを書きます。
設計書は、どう作るかを書いた文書です。読み手は作る側だけです。内部の構造や処理の流れを書きます。発注する側が読む必要はありません。
この3つのうち、揉めごとの原因になるのは仕様書です。要件定義書は抽象的なので齟齬が表に出にくく、設計書は作る側の内部文書なので外との齟齬になりません。仕様書は、発注する側と作る側の両方が読み、両方が違う解釈をしうる文書です。だから、仕様書だけは曖昧さを許さない書き方をする必要があります。
3つを1つのファイルにまとめる進め方もありますが、規模が小さい場合に限ります。項目が100を超えると、目的と振る舞いと構造が混ざったファイルは読めなくなります。分けるか分けないかは、読み手が同じかどうかで決めてください。読み手が違う内容を同じ文書に入れると、どちらの読み手も自分に関係ない部分を読み飛ばし、結果として読まれない文書になります。
揉めるのは、決めた事の置き場所が決まっていないから
仕様書があるのに揉めるチームには、共通した状態があります。決定が複数の場所に散っていることです。
よくある散り方はこうです。最初の仕様書はファイルとして作られます。その後の変更は打ち合わせで決まり、議事録に書かれます。細かい確認はチャットで行われ、そこで決まります。さらに細かい調整は、作業の管理表のコメント欄に書かれます。結果として、ある項目の最終的な決定がどこにあるのかを、誰も断定できなくなります。
この状態で「仕様書のとおりに作った」と「そういう話ではなかった」が衝突します。どちらも嘘をついていません。参照した場所が違うだけです。
対処は2つあります。1つは、決定の置き場所を1つに決めて、他の場所で決まったことを必ずそこへ書き戻すことです。もう1つは、そもそも決定が生まれる場所に仕様書を置くことです。
後者のほうが続きます。書き戻す運用は、忙しい時期に必ず飛びます。作業の単位ごとに仕様の記述を持たせて、その作業についてのやり取りが同じ場所に残る形にすると、書き戻す工程そのものがなくなります。1つの作業を開けば、何を作るのかと、途中で何が決まったのかが同時に見えます。カードの中に書式のある説明欄を持てる形なら、仕様の記述をそこに置けます。どこまで書けるかはできることのページに、説明欄とコメントの扱いとして並んでいます。
置き場所を決めたら、周知します。周知していない決まりは守られません。「仕様に関する決定は、この場所に書かれたものだけが有効」と明示して、チャットで決めたことはその場で書き写す、と全員に伝えてください。
書き方の5つの手順
書く順番があります。この順番を守ると、手戻りが減ります。
手順1 目的と、達成されたと判断できる条件を先に書く
仕様の前に、何のためかを1文で書きます。そして、どうなれば完成と言えるかを箇条書きで書きます。ここが曖昧なまま仕様を書き始めると、後から「そもそもこれは何のためだったか」に戻ります。判断できる条件は、確かめる人が誰でも同じ結果になる形にします。
手順2 範囲の外を書く
やらないことを先に書きます。ここが最も効く手順です。範囲の外が書かれていない仕様書は、書かれていない機能について「当然入っていると思った」という主張を許します。今回は作らないものを列挙しておけば、その主張は起きません。やらないことを書くほうが、やることを書くより揉めごとを減らします。
手順3 画面と項目を並べる
画面ごとに、そこに出る項目を並べます。項目には、名前、種類、必須かどうか、初期の値、入力できる範囲を書きます。ここを表にすると読みやすくなります。文章で書くと、項目の抜けに気づけません。
手順4 操作と、そのときの振る舞いを書く
操作を主語にして書きます。「保存を押したとき、入力の確認をして、問題がなければ一覧に戻る」という形です。ここで重要なのは、問題があったときの振る舞いも書くことです。正常な場合だけを書いた仕様書は、実装の段階で必ず質問が発生します。
手順5 例外と境界を書く
数の上限、文字数の上限、同時に操作されたときの扱い、権限のない人が開いたときの扱い。ここが書かれていない仕様書は、後から追加の作業を呼びます。境界の値は必ず具体的な数字で書いてください。「適切な長さ」と書かれた項目は、作る側が勝手に決めます。
仕様書に必ず入れる項目
文書の頭に入れる項目を挙げます。本文より先に、ここを整えてください。
文書の題と、対象の範囲を1行で書きます。何についての仕様書かが題で分かる状態にします。
版の番号と、更新の日付を書きます。版の番号がない仕様書は、複数の版が同時に流通します。更新の日付だけでは、どちらが新しいかの判断を日付の比較に頼ることになり、同じ日に2回更新されたときに区別できません。
決定した人と、確認した人を書きます。仕様の内容について後から質問が出たときに、誰に聞けばよいかが分かります。ここが空欄だと、聞く先を探す時間が発生します。
変更の履歴を表で持ちます。いつ、どこを、なぜ変えたかの3列です。なぜの列が最も重要です。変更の理由が残っていれば、半年後に同じ議論を繰り返さずに済みます。
関連する文書の場所を書きます。要件定義書、設計書、確認の結果。リンクで示せるなら、リンクにします。ファイル名だけを書くと、置き場所が変わった時点で辿れなくなります。
用語の一覧を持ちます。同じものを違う名前で呼んでいる状態は、どの現場にもあります。「顧客」と「取引先」と「アカウント」が同じものを指しているなら、1つに決めて一覧に書きます。3つの呼び方が混在した仕様書は、読む人ごとに違う理解を生みます。
伝わる書き方と、伝わらない書き方
同じ内容でも、書き方で伝わり方が変わります。3つの原則があります。
1文に1つのことだけを書きます。「保存を押すと入力を確認して一覧に戻り、エラーがあれば赤く表示して留まる」は、4つのことが1文に入っています。読む側が条件の分岐を頭の中で組み立てる必要があり、誤読が起きます。文を分け、条件ごとに行を分けてください。
主語を書きます。「確認する」と書かれていても、誰が確認するのかが書かれていなければ、作る側は自分が実装する処理だと解釈し、発注する側は人が確認する手順だと解釈します。主語が省かれた仕様書は、この種の齟齬を量産します。
画面に出る名前で書きます。開発の中で使っている内部の呼び方で仕様書を書くと、発注する側が確認できません。逆に、発注する側の社内の通称で書くと、作る側が分かりません。画面に表示される文字をそのまま使うのが、双方に通じる唯一の書き方です。
避けるべき言葉があります。「適切に」「必要に応じて」「基本的に」「原則として」「等」「など」。これらは、書いた時点では合意しているように見えて、実装の段階で解釈が分かれます。「必要に応じて通知する」は、どの条件で通知するのかが決まっていません。条件を書けないなら、まだ決まっていないということなので、未決定として明示してください。未決定と書くことは恥ではなく、決まっていないのに決まったように書くほうが問題を生みます。
数字を伴う記述は、単位と境界の扱いを添えます。「10件まで」は、10件を含むのか含まないのかで結果が変わります。「10件以下」と書けば疑いが残りません。
表計算で書くときの組み方と限界
仕様書を表計算で書くチームは多く、理由もあります。項目の一覧を表で持てること、既存のファイルがあること、誰でも開けることです。組み方の要点を挙げます。
1枚目を目次と版の履歴にします。2枚目以降を画面ごとのシートにして、シート名を画面の名前にそろえます。項目の表は、列を固定します。名前、種類、必須、初期の値、範囲、備考の6列です。列の並びがシートごとに違うと、読む側が毎回目で探すことになります。
振る舞いの記述は、条件と結果の2列の表にします。文章で書くより抜けに気づけます。条件の欄には「正常」だけでなく「未入力」「上限を超えた」「権限がない」の行も並べておきます。行が空欄で残っていれば、そこが未決定だと分かります。
限界は2つあります。1つは、同時に触れないことです。複数人で確認しながら編集すると、入力が消えます。もう1つは、作業の記録と離れることです。仕様書のファイルが1つあり、作業の一覧が別にあり、やり取りがさらに別にある状態は、前の節で触れた散らばりそのものです。
表計算で書き続けるなら、最低限、決定の書き戻しの担当を1人決めてください。それがないと、ファイルは3か月で古くなります。実際には、ファイルが古いことに気づかずに参照されるほうが、古いこと自体より深刻です。
作業の単位に仕様の記述を寄せる形に移す場合は、いま持っている資料が運べるかを先に確かめます。カードや添付やコメントがどこまでそのまま運ばれるかはTrelloからの移行のページに項目ごとに並んでいます。
変更が入ったときの扱い
仕様は変わります。変わらない前提で運用すると、変わった瞬間に文書が信用されなくなります。
変更の受け方を決めておきます。誰が変更を申し入れられるか、誰が承認するか、承認されたらどこを更新するか。この3つを最初に決めます。決めていないと、口頭で伝えられた変更が実装され、文書が追いつかない状態になります。
版の上げ方は単純にします。内容が変わったら小数点の下を1つ上げ、範囲が変わったら整数を上げる形で足ります。細かい規則を作ると守られません。
変更の履歴に、影響の範囲を書きます。ある項目を変えると、別の画面の振る舞いが変わることがあります。その連鎖を履歴に書いておかないと、後から「なぜこの画面がこうなっているのか」が分からなくなります。
そして、変更の合意を残します。打ち合わせで決まった変更を、その場の口頭だけで終えないでください。決まった内容を文字にして、相手に確認してもらった記録が残っている状態にします。金額や納期に関わる変更は、特にここを省かないようにします。取引の条件に関わる判断が必要な場合は、所管の窓口や専門家に確認してください。
変更が多すぎる場合は、仕様書の書き方ではなく手前の工程に問題があります。目的と、達成されたと判断できる条件が固まっていない状態で仕様を書き始めると、変更が止まりません。1週間に5件以上の変更が出ている状態なら、手順1に戻ってください。
確認の回し方
書いた仕様書を確認してもらう工程には、進め方があります。
全部を書き上げてから確認に出すと、直しが全体に及びます。画面が3つ書けた時点で1度出す形にすると、書き方の方向そのものを早く直せます。分量が少ないほど、確認する側も読んでくれます。
確認を依頼するときは、見てほしい点を指定します。「確認をお願いします」だけで送ると、誤字の指摘しか返ってきません。「範囲の外に入れた3項目が妥当か」と書けば、そこについての判断が返ります。
確認の期限を書きます。期限のない依頼は後回しにされ、待っている間に実装が先に進んで手戻りになります。期限までに返事がない場合にどうするかも書いておきます。「返事がなければこの内容で進めます」と添える形が実務的です。
確認の結果は、文書に反映したうえで、反映したことを返します。指摘を受けて直したのに、直したことを伝えないと、同じ指摘が次の版でも来ます。
確認をする側が複数いる場合、意見が食い違うことがあります。そのときは、どちらが決める立場かを先に決めておきます。決める人が決まっていない確認は、いつまでも終わりません。
そのまま使える構成の見本
構成に迷ったときの並びを挙げます。画面を伴う機能の仕様書を想定しています。
先頭に、文書の題、版、更新日、決定した人、確認した人を置きます。次に目的を1文、達成されたと判断できる条件を3つから5つ、そして範囲の外を箇条書きで並べます。ここまでで1ページです。
続いて、登場する役割を並べます。誰が使う機能なのかを、権限の区分で書きます。管理する人だけが使えるのか、全員が使えるのか、社外の相手にも見えるのか。ここを書いておかないと、実装の途中で権限の質問が出ます。
次に、画面の一覧です。画面の名前と、その画面の役目を1行ずつ並べます。画面が5つあるなら5行です。この一覧があると、後から画面が追加されたことが分かります。
画面ごとの詳細に入ります。項目の表、操作と結果の表、例外の表の3つを、画面ごとに同じ順番で並べます。順番をそろえることが要点です。画面ごとに構成が違うと、読む側が毎回探します。
最後に、用語の一覧と、関連する文書の場所を置きます。用語の一覧を末尾に置くのは、参照されるのが読んでいる途中だからです。先頭に置くと、読み始める前に用語の説明を読むことになり、頭に入りません。
分量の目安は、画面1つあたり1ページです。これを超えるなら、画面の役目が多すぎる合図です。仕様書の分量が多いことは、たいてい作るものが複雑すぎることの表れで、文書の書き方の問題ではありません。
書き終えたあとに読み直す観点
書いた本人が見直すときの観点を5つ挙げます。他人に確認を依頼する前に、ここを自分で通してください。
1つ目は、主語のない文を探すことです。文書を上から読んで、誰がするのかが書かれていない文に印を付けます。この作業だけで、齟齬の半分が消えます。
2つ目は、条件の分岐が全部埋まっているかです。操作と結果の表を見て、正常な場合の行しかない画面がないか確かめます。未入力のとき、上限を超えたとき、権限がないときの3行が入っていれば、最低限は足ります。
3つ目は、数字に単位と境界が付いているかです。「以上」「以下」「未満」「を超える」のどれかが書かれているかを見ます。書かれていない数字は、必ず解釈が分かれます。
4つ目は、避けるべき言葉が残っていないかです。文書の中を「適切」「必要に応じて」「等」で探してください。見つかった箇所は、条件を書けるか、未決定と書くかの2択です。
5つ目は、範囲の外が最新かです。書き進めるうちに、範囲の外に入れたはずの項目を仕様に書いてしまっていることがあります。矛盾したまま出すと、確認する側が混乱します。
この5つは20分で通せます。確認に出す前の20分で、往復が1回減ります。
委託先に渡すときに足すもの
社外の相手に仕様書を渡す場合、社内で使っているものに足す内容があります。
前提の環境を書きます。社内では当たり前になっている条件が、外の相手には分かりません。どの環境で動く必要があるのか、どの範囲を対象にするのかを明示します。
用語の一覧は、社内向けより厚くします。社内の通称は、外の相手には通じません。通称を使わずに書き直すのが理想ですが、完全に排除するのは難しいので、一覧で補います。
確認の方法と、受け入れの条件を書きます。何をもって完成とするかが書かれていない仕様書を渡すと、検収の段階で揉めます。達成されたと判断できる条件を、確かめる手順の形で書いてください。
質問の窓口と、返答にかかる時間の目安を書きます。質問の宛先が書かれていないと、作業が止まった状態で相手が待つことになります。1営業日以内に返すと書いてあれば、相手は他の作業に移れます。
変更の扱いも明記します。仕様が変わったときに、金額や期限をどう扱うか。ここを書かずに進めて、後から追加の作業について交渉になる例はよく聞きます。契約や金額の扱いに踏み込む判断が必要な場合は、所管の窓口や専門家に確認してください。
渡す形式も決めます。編集できる形で渡すのか、読むだけの形で渡すのか。編集できる形で渡すと、相手が直した版と自分の版が分岐します。分岐したら、どちらが正かを決める手間が生まれます。
仕様書が読まれない状態への対処
きちんと書いたのに読まれていない、という状況はよく起きます。原因は3つに絞れます。
1つ目は、長すぎることです。50ページの仕様書は、実装する人が必要な箇所だけを探して読みます。全体を読む人はいません。対処は、俯瞰の部分を薄くして、詳細を作業の単位に分けることです。
2つ目は、どこが最新か分からないことです。版の番号が付いていない、あるいは複数の場所に似たファイルがあると、読む前に確認の手間が発生します。その手間が、読まない理由になります。
3つ目は、読んでも判断できないことです。曖昧な言葉が残っていると、読んだ側が結局質問することになります。質問して答えが返るなら、最初から質問したほうが速い。こうして文書は迂回されます。
3つのどれに当たっているかは、実装している人に聞けば分かります。「どこを見て作っていますか」という質問に、仕様書以外の名前が返ってくるなら、その場所が実質的な仕様書です。だとすれば、そこに書くようにしたほうが早いです。
そして、迂回されている状態を放置しないでください。文書が読まれないまま作業が進むと、後から入った人が最初に読むのはその文書です。古い内容を信じて作業を始め、途中で実態と違うことに気づく。この遠回りが、新しい人が入るたびに繰り返されます。
小さな改修の仕様はどこまで書くか
新規の機能ではなく、既にあるものを少し直す場合の書き方も決めておくと、迷いが減ります。
小さな改修に本格的な仕様書は要りません。ただし、3つだけは必ず書きます。直す前の振る舞い、直した後の振る舞い、そして直さない範囲です。この3点があれば、実装も確認も進みます。
直す前の振る舞いを書くのが抜けやすい項目です。書いていないと、確認する人が「元からこうだったのか、今回変わったのか」を判断できません。元の振る舞いを1行書いておけば、確認は差分だけで済みます。
直さない範囲は、新規のときの範囲の外と同じ役目です。似た画面が3つあって1つだけ直す場合、他の2つは直さないと明示します。書いていないと、なぜ揃っていないのかという指摘が後から来ます。
書く場所は、作業の単位で足ります。改修ごとに別のファイルを作ると、ファイルが増えて追えなくなります。カードの説明欄に3点を書いて、やり取りをそのカードのコメントに残す形にすると、半年後に「なぜこの仕様になっているのか」を辿れます。
改修が積み重なると、元の仕様書と実際の振る舞いがずれます。ずれを放置すると、次の改修で元の仕様書を参照した人が誤ります。四半期に1度、実際の振る舞いに合わせて俯瞰の文書を直す時間を取ってください。半日で足ります。
俯瞰の文書を直す時間を確保できないチームは、直す対象を絞ってください。全部を最新にするのは無理でも、画面の一覧と用語の一覧と範囲の外の一覧の3つだけを最新に保てば、参照した人が誤る場面はかなり減ります。細かい振る舞いは作業の記録に残っているので、そこを辿れば足ります。
仕様と作業と会話を同じ場所に置く
最後に、揉めごとを構造から減らす置き方について書きます。
仕様書が独立したファイルとして存在していると、必ず3つの分離が起きます。仕様と作業の分離、仕様と会話の分離、そして仕様と実際に作られたものの分離です。この3つの分離が、齟齬の温床です。
作業の単位に仕様を寄せると、分離が減ります。1つの作業のカードに、何を作るのかの記述があり、そのカードのコメントにやり取りが残り、そのカードの状態が進み具合を示す。この形なら、ある機能について知りたい人は1か所を開けば足ります。過去の決定を探すときも、その作業を開けば経緯が並んでいます。
全体を俯瞰する文書は、それでも要ります。画面の一覧、用語の一覧、範囲の外の一覧は、1か所にまとまっていたほうが読めます。俯瞰の文書と、作業ごとの記述を分けて、俯瞰のほうを薄く保つのが現実的な形です。
この運用をするには、誰が何をいつ変えたかの記録が残っている必要があります。仕様の記述が書き換えられたときに、誰が書き換えたのかが分からないと、変更の経緯を追えません。操作の記録の残り方は安全性の考え方のページに、操作ログとログイン履歴の扱いまで説明されています。社外の委託先を含めて同じ場所を使う場合は、見せる範囲を絞る設計も同じページにあります。
道具を替えるかどうかの判断は、いまのやり方で決定が散っているかどうかで決めてください。散っていないなら、表計算のままで問題ありません。散っているなら、書き方を整える前に置き場所を1つにするほうが効きます。上限や人数の数え方は料金のページ、他の道具と並べた条件の違いは比較の一覧、細かい疑問はよくある質問に整理されています。仕様書の書き方の型は、決定が1か所に集まって初めて機能します。
Q1. 仕様書と要件定義書はどう書き分けますか？
要件定義書は何のために作るかと何ができればよいかを書き、発注する側と作る側の合意の対象になります。仕様書は何をどう振る舞わせるかを書き、画面の項目や操作したときの結果、条件が満たされないときの動きまで含めます。読み手が違う内容を同じ文書に入れると、どちらの読み手も自分に関係ない部分を読み飛ばします。
Q2. 仕様書に最初に書くべきなのは何ですか？
目的と、達成されたと判断できる条件を先に書き、その次に範囲の外を書きます。やらないことを列挙しておくと、書かれていない機能について「当然入っていると思った」という主張が起きません。項目や振る舞いから書き始めると、後から目的に戻る手戻りが発生します。
Q3. 仕様書で使わないほうがよい言葉はありますか？
「適切に」「必要に応じて」「基本的に」「等」「など」は避けてください。書いた時点では合意しているように見えて、実装の段階で解釈が分かれます。条件を具体的に書けない箇所は、まだ決まっていないということなので、未決定と明示してください。数字は「10件以下」のように境界を含むかどうかが分かる形で書きます。
Q4. 表計算で仕様書を書き続けても問題ないですか？
規模が小さければ問題ありません。限界は2つで、複数人が同時に編集すると入力が消えること、そして作業の記録ややり取りと離れて決定が散ることです。表計算で続けるなら、チャットや打ち合わせで決まった内容をファイルへ書き戻す担当を1人決めてください。それがないとファイルは3か月で古くなります。