設計書の書き方｜読み手に伝わる構成と表現のコツ

当サイトの記事は編集部が国土交通省・IPA・デジタル庁などの公的機関の情報、規格や業界団体の公開情報を調べて独自に執筆しています。記事内にIT・Webエンジニアの転職サービスへの案内（広告）を含みます。

設計書の書き方の基本は「読み手を先に決める」

『とにかく全部書いておけば安心』と思いがちですよね。ただ、読み手を考えずに書いた設計書は、情報が多いのに肝心な所が見つからない文書になりやすいんです。

ソフトウェアの設計書は、読む人によって知りたいことが違います。編集部が整理すると、次のようになります。

設計書の種類ごとの役割は設計書とは？システム開発の設計書の種類と役割で紹介しています。

設計書の作り方の流れ

文章を「決めたこと・理由・決めていないこと」で書き分ける

『決めていないことまで書くの？』と驚く方もいるかもしれません。実は、決まっていないことを書かずにおくと、読む人が勝手に想像して作ってしまうんです。

デジタル庁のDS-100（デジタル・ガバメント推進標準ガイドライン）でも、要件定義書について、未確定な要件はリスク要因になり得ることに留意し、その旨を要件定義書で明らかにするとしています。設計書でも同じ考え方が役に立ちます。

3つの書き分け表

次の表は、編集部が社内の備品を貸し出すシステムを例に作った、架空の書き分け例です。

3つを同じ段落に混ぜてしまうと、『延長はできるの？できないの？』と読む人が迷います。見出しや表で分けておくと、どこが確かな話なのかが一目で分かります。

読み手に伝わる表現のコツ

設計書の文章で、いちばん多い失敗があいまいな言葉です。書いた本人には意味が分かっていても、読む人には伝わらないことがよくあります。

規格の書き方を定めたJIS Z 8301:2019では、要求事項は客観的に確かめられるものだけを書き、「十分に強い」のような表現を使わないという考え方が示されています。設計書でも、そのまま参考になる考え方です。

あいまいな言葉の直し方

文末と言葉をそろえる

同じJIS Z 8301では、要求は「…しなければならない」「…する」「…とする」、推奨は「…することが望ましい」、許容は「…してもよい」のように、文末で意味を書き分けるとしています。設計書でも、文末の意味を決めておくと読み間違いが減ります。

設計書作成要領で約束をそろえる

チームで設計書を書くなら、書き方の約束を「設計書作成要領」のような文書にまとめておくのがおすすめです。用語の一覧、文末の使い分け、図の描き方、版の付け方などを決めておくと、人が変わっても書き方がぶれません。

書いたあとのチェックは設計書・仕様書のレビュー観点でくわしく紹介しています。

場面別の設計書の作り方

『自分の場面だと何を書けばいいの？』という方のために、よくある場面ごとのポイントを並べますね。

プログラムとVBAの設計書の書き方

プログラムの設計書では、処理の流れを条件の分かれ目ごとに書くのが基本です。VBAのような小さな業務ツールでも、『自分しか使わないから』と書かずにおくと、担当が変わった時に誰も直せなくなってしまいます。

小さなツールなら、1枚の表に「使う人」「元になるファイル」「ボタンごとの動き」「エラーの時の扱い」をまとめるだけでも役に立ちます。プログラムの設計書は詳細設計書とは？、VBAの仕様のまとめ方はExcel VBA・業務ツールの仕様書の書き方で紹介しています。

JSONの設計書の書き方

APIでやり取りするJSONのデータは、項目ごとに名前、型、必須かどうか、例の値を表にまとめると伝わりやすくなります。APIの設計を、OpenAPI Specificationという公開された書式で書く方法もあります。くわしくはAPI仕様書の書き方で紹介しています。

業務委託での設計書の作り方

業務委託で設計を頼む時や受ける時は、設計書に何をどこまで書くかを、契約の前にそろえておくことが大事です。IPAの共通フレーム2013のガイダンスでは、企画や要件定義の一部を発注する場合に「請負」か「準委任」かの区別をしておくのがよい、としています。

委託範囲と成果物の決め方は業務委託の仕様書の書き方でまとめています。

設計書の書き方でよくある相談

知恵袋に寄せられた相談の中から、閲覧の多いものを要約してお答えしますね。

相談1：データベースの設計書の書き方が分からない

『勤怠を管理するシステムを作ろうとしていて、データベースの設計書の書き方が分からない』という相談です。

データベースの設計書は、「表で書く部分」が中心です。テーブルごとに項目の名前、型、必須かどうか、説明を表にし、テーブル同士の関係は図で描くと分かりやすくなります。書き方はテーブル定義書・データベース設計書の書き方で紹介しています。

相談2：設計書の文章をすっきりさせたい

『設計書の文章が長くなりがちで、すっきりさせるコツを知りたい』という相談です。

いちばん効くのは、1文に1つのことだけを書くことです。条件が2つ以上あるなら、文章ではなく箇条書きや表に移してみてください。

「決めたこと」と「理由」を同じ文に入れないのもコツです。理由は別の行に分けると、本文がぐっと短くなります。

相談3：ドキュメントづくりに時間をかけすぎている気がする

『SEとして働き始めたら、ドキュメント作成ばかりで時間がかかる』という相談です。そう感じる気持ちも分かりますよね。

設計書は、読み手が迷わずに作業できれば役目を果たします。誰も読まない欄まで細かく埋めるより、読み手が聞きに来そうな所を先に書くほうが、結果として時間の節約になります。

設計書の作成ツールと、書き方の学び方

『設計書を作成するツールは、フリーの物でも大丈夫？』と気になる方もいますよね。大丈夫です。大事なのはツールより、チームで同じ形式と約束をそろえることです。

ツールの選び方は仕様書の作成ツール、ひな形の使い分けは設計書のテンプレート・サンプルで紹介しています。

書き方の本や公的な資料で学ぶ

設計書の書き方の本は、ソフトウェア設計や要件定義の本の中に章として入っていることが多いです。公的な資料では、IPAの共通フレーム2013やユーザのための要件定義ガイド 第2版が、開発の流れや文書の考え方を知るのに役立ちます。

設計書を書く力は、要件定義や設計といった上流工程を任される職場で評価されやすい力です。今の担当工程から一歩進みたい方は、求人の仕事内容で「設計書の作成」がどう書かれているかを比べてみると、道が見えてきます。今の職場で書く機会を増やしていく道も、もちろんありです。

よくある質問

まとめ

あわせて読みたい

設計書のテンプレート・サンプル｜Excel・Markdownの使い分け

設計書・仕様書のレビュー観点｜見落としを防ぐチェックリスト

仕様書とは？意味と目的、設計書・要件定義書との違い