設計書の書き方　書く前に知っておきたい９つの注意点

こんにちは！
複数の億規模プロジェクトでPLやってるやまさんです！

設計書って結局なに書いたらいいんだろう…

設計書作成の仕事をやるようになると、設計書の書き方に悩みますよね^^;

エンジニア歴が長い方でも「設計書は奥が深い」と感じる場合もあるんじゃないでしょうか。

この記事ではボクが日々意識している設計書の書き方を紹介してみます。

ボクは今でこそPL（プロジェクトリーダー）をやってますが、「プログラマ→システムエンジニア→PL」という感じで進んできました。

こんな経歴もあってか、そこそこの数の設計書を書いてるので何か役に立てるとうれしいです。

実のところ、今でも基本設計書の章立てや全体概要の章ぐらいは書いてるんですけどね^^

自分で書いた方がプロジェクトをコントロールしやすかったりなど理由があるんですが、それはまたの話ということで…^^

ということで、今回は「設計書の書き方」というテーマでいきたいと思います！

ぜひ読んでみてください！

設計書の書き方の前に…なぜ設計書を書くのか

そもそもなんで設計書は書かないといけないんでしょうか。

設計書を書く理由は次の４つです。

極論を言うと、「どんなシステムを開発するか」関係者で認識があっていたら書く必要ないと思いません？

現実ではありえないですが…

現実的でないので、↑の４つを達成するために設計書を書いていくことになります。

詳しく説明していきますね。

記録のための設計書

人間忘れる生き物です。

大切なことでもすぐ忘れてしまいますね^^;

ここなんでこの仕様にしたんだっけ？

システム開発のあるあるですよね^^;

履歴を含めて検討結果の”記録”を残すための役割を設計書は持ってます。

伝達のための設計書

システム開発ではいろんな人が関わります。

工程が進むとエンジニアを増員したり、また人事で担当者が変わったりすることがありますよね。

増員、人員の配置換えがあったとき、毎回イチから全部説明するのってめんどくさくないですか？^^;

なので、設計書はどんなシステム作るのか”伝達”する役割もあります。

証明のための設計書

こんな仕様にしてとか頼んだっけ？

リリース直前でお客さんからたまに言われるこの一言…

なんだ…と……

ってなりますよね^^;

そんなときに設計書は”証明”としての役割を担ってくれるんですよね。

もちろん議事録という手段もあるんですが、議論の結果、決まったことは最低限設計書にも書くのでモメたときに役立ってくれます。

設計書の書き方と必須の記載内容

では、設計書の書き方を紹介していきますよ！

設計書を書くときに気を付けるべきことは次の９つです。

順番に説明していきますね！

設計書の書き方①：何の設計書か最初に書く

まずはこれから作成する設計書が何の設計書なのか書き出します。

給与管理システムの設計書なのか、在庫管理システムの設計書なのか、などですね。

なんの設計書なのか書く理由はたった1つ。

後で見たとき分かりやすいから、です。

設計書ってシステム開発プロジェクトが終わっても見ますよね。

むしろ、システムは使われてなんぼの世界なので、リリースしてからが本番といってもいいでしょう。

「何の設計書なのか」を書いておけば、リリース後仕様を知りたいとき、この設計書は読み進めるべき設計書なのか判断がつきやすいんですよ。

設計書が1つとは限りませんしね^^;

なので、必ず記載するようにしましょう。

設計書の書き方②：プロジェクトの目的と背景も書く

プロジェクトの目的と背景も設計書の冒頭に書いてしまいましょう。

「何の設計書なのか」とワンセットですね^^

正直、ボクがこの記事で一番伝えたかったのは「プロジェクトの目的と背景」を設計書に書きましょうという点なんですよ。

設計をしてると「ここの仕様」どうしようという場面に出くわすと思います。

そのとき立ち返るのが「プロジェクトの目的と背景」。

この記述はどんな仕様にするか迷ったときの判断基準になってくれるんですよね。

判断基準を明確にしておくことで自分や他のメンバーが迷ったとき、システム導入の目的に沿った判断ができる可能性が上がります。

ホントに書くか、書かないかでかなり変わってきますよ。

ちなみにボクは目次の後ろあたりに「はじめに」という章を作ってそこに書くようにしてます。

”設計”ではないですが、「プロジェクトの目的と背景」は設計の方針ともいえる内容なので書いておきましょう。

なお、作成した設計書はお客さんへ説明することになると思います。

このとき、「プロジェクトの目的と背景」があると、説明がうまく流れやすいというメリットもあります。

設計書の書き方③：章立てを考える

「何の設計書なのか」「プロジェクトの目的と背景」が書き終わったら、設計書の章立てを考えましょう。

目次があるなら、目次が章立てになりますよ^^

章立ては職場でテンプレが存在している場合があります。

その場合はテンプレを持ってきてテンプレに不足がないか確認しましょう。

ちなみに、考えた目次案の各章にどんな内容を書く章なのかメモしておくのがオススメです。

メモつきの目次案を作成すれば、抜け漏れが無いかチェックする資料に使うことができるんですよね^^

なお、先輩や知識のある人にメモつき目次が完成した段階でレビューしてもらうのもいいですよ。

サクッと作れる上に今後の方向性や大まかな作業分量が分かる資料になるのでコスパ抜群です^^

設計書の書き方④：全体→詳細を意識して書く

章立てが決まったら、全体→詳細を意識して設計書を書いていきます。

全体→障害は資料作成でよく言われるやつですね。

なお、ボクはよく”ナンバリング”と呼ばれる方法で書いていくことが多いです。

例文はこんな感じ。

↑の「１．開発概要」のところに、簡単な業務フローを載せたりすることもありますね。

また、他システムとの連携処理があれば、そこにも簡単に触れます。

あげたらキリがないですが、ここでは「３つの機能から…」という表現方法に注目してください。

この表現方法はめちゃ使いやすく、さらに読み手も分かりやすいのが特徴です。

設計書を書く時だけでなく、ナンバリングはプレゼン資料などにも使える汎用的なワザなので覚えておくとが良いかと思います。

設計書の書き方⑤：図を使ってイメージを共有

実は文章で伝えるのって難易度が高いんですよね^^;

なので、文章が複雑になりそうな場合は図を使えないか考えます。

特に全体像を説明する場合に図を使うと、とても分かりやすくなりますよ^^

ちなみに”図”っていうのはこういうやつです。

ただ、”図”には注意点があります。

注意点としては「図は細かな内容を示すのに向いていない」という点。

パワポを使ったプレゼンで

プレゼン聞きながら資料見てそのときは分かった気がしたけど、気分だけだった…

そんなことありませんか？

図は全体概要を把握するのには向いているのは確かです。

ですが、逆に図は細かな内容を把握するのには向いてないんですよね^^;

図と文章を使い分けできると、設計書のレベルがグッと上がります。

ぜひ活用してみてください！

設計書の書き方⑥：処理条件などパターン分岐するものは表にする

”図”の話をしたので、”表”の話もしたいと思います。

設計書を書く上で表もどんどん活用していきましょう。

表は処理条件などパターン分岐する内容を伝えたい場合に有効です。

”表”は次のようなやつですね。

↑の表は”Y” ”N”でパターンを整理してますが、”〇”　”×”でも、”有””無”でも中身が分かればOKです。

表で情報を整理すると、パターンの検討漏れも発見しやすいですよ！

システム開発をやっていると、試験工程でバグが見つかると思います。

で、バグ原因ですが、”処理パターンの考慮漏れ”ってけっこう多くありませんか？

表を書いて整理しておくと、読む側も把握しやすいです。

さらにパターン考慮漏れのバグも事前につぶすことできるのでこれもオススメです^^

設計書の書き方⑦：特殊仕様はその仕様にした理由も書く

「なぜその仕様にしたのか」という理由を設計書に書いておきましょうという注意点です。

システム開発をやっていると、例外ケースに対応するために特殊な仕様にすることってありませんか？

特殊仕様って、しばらくして設計書を見た時に「なんでこんな変な仕様にしてるんだ…」ってなることがあるんですよね。

歴史の長いシステムだと、例外処理が大量にあったりします…

レガシーなシステムでは例外処理がホントに多いので、「”例外”って意味知ってる？」ってなります^^;

でも、今、まさに設計している自分たちや関係者はいいんですよ。

ただ、数年もたつと開発に携わっていた人がその担当にいるとは限りません。

なので、特殊仕様を設計した場合はその設計理由もきっちり明記しておきましょう。

設計書の書き方⑧：形式的に気をつけた方がいい書き方

ここからは形式的にチェック可能な設計書の書き方の注意点を説明していきます！

すぐ実践できる内容なので、ぜひ試してみてくださいー

あいまいな表現は排除！（主語、目的語、指示語を確認）

あいまいな表現は避ける、というやつですね。

あいまいな文章は次のどれかに該当することが多いです。

多少、くどい感じになってもいいので、設計書ははっきり書くことが大切ですよ！

似た用語は統一

似た用語は統一しましょう。

よくあるのが日付系の用語ですね。

実行日と処理日ってなにか違うの？

って、なります^^;

違う意味で使っているなら、用語集的なものを作ってしまうのも1つの手段ですよ。

その他にも、次のような「意味は分かるけど、表記がまちまち」になりそうなものも統一しておくのがよいです。

自分や社内用のメモでそこまで気にしなくても良いんですが、お客さんへ納品する設計書は統一しておいた方がいいですね。

1文は2行（60～70文字）以内に

どんな文章でもですが、1文は短いほうが分かりやすいです。

目安としては長くても1文、60～70文字を限度にするのがオススメ。

Wordだと、だいたい2行弱ぐらいですね。

例えば、次の文章はどっちが分かりやすいでしょうか。

だいぶすっきりしたんじゃないでしょうか。

（1文が長い文章を意識して書いたことないので難しかった…）

ちなみに”箇条書き”を使うとさらに見やすくなります。

”箇条書き”はいろんな場面で使用できる万能テクニックなので、日頃から意識して使ってみるのオススメですよ！

設計書の書き方⑨：「現行通り」は使わない。使ってはいけない

最後のポイントです。

設計書を書くうえで「現行通り」「現仕様通り」「既存仕様通り」という言葉は使わないでください。

「書かないでください」ってそれ書き方のポイントなの？

正直、「”既存仕様通り”は禁止」のポイントは書き方に入れるか迷いましたが、書くとこがなさそうなので入れちゃいました^^;

「既存仕様通り」と書いてはいけない理由は次の通りです。

特に一番マズいのが１つ目の「”既存仕様”の認識が設計書作成者、エンジニア、お客さんで確実にズレる」ですね^^;

なぜか、「既存仕様通り」というと、みんな自分たちの都合のいいように解釈するんです。

ホントにみんな自分の都合のいいように解釈します。

あ、唯一、都合よく解釈しないのは「「既存仕様通り」と書いた設計書で痛い目を見たエンジニア」だけですね^^;

まあ、社内だと、まだコーディングなどの工程で認識合わせを行う機会を設定できるのでまだマシなんです。

多少、炎上するぐらいでなんとかなるケースがほとんどでしょう←

ですが、お客さんとの認識祖語があった場合、最悪、リリース直前で徹夜対応のパターンになります（泣）

なので、「既存仕様通り」ではなく、「〇〇という仕様に合わせ」といった感じで”既存仕様”を設計書に記載しましょう。

補足：設計書作成は”書く”以外のことも大切

ここからは補足的な内容です。

設計書の書き方とは直接関係ないですが、意識しておくと役立つと思いますよ！

レビューの重要性

レビューめんどくさい…って思うかもしれません。

ですが、1時間レビューするだけで、試験工程で改修に数日かかるバグを見つけることも結構あるんですよね。

設計工程では設計書の修正だけで済みますが、試験工程で見つけると、設計→コーディング→再試験となって量が単純に増えるからというのもあります^^;

未来に時間を投資すると思って、レビューはめんどくさがらずやりましょう。

変更履歴は必ず残す

忙しいと忘れがちですが、変更履歴も必ず残しましょう。

最近は便利なツールが出ているので大丈夫かもしれせんね^^

ですが、いまだにWord、Excelで設計書を作って納品しているとこも多いと聞きます…

お客さんの都合ですが、ボクの職場も設計書はWord、Excelで作成して納品してます

特に設計書のページ数が多いと、「いつの間にか設計書が修正されていて気付かなかった…」というのこともしばしば^^;

「いつ」「どこの記載を」「〇〇→ｘｘへ」「どういう理由で」修正したか、しっかり管理しましょう。

まとめ：設計書を書く時は「後から見て意識祖語なく伝わるか」を意識するのポイント

この記事では次のようなことを紹介しました。

いかがでしたでしょうか。

今回はシステムエンジニアが主に行う仕事である「設計書の書き方」について紹介してみました。

今回の記事で、設計書を書く上でも「プロジェクトの目的と背景」が重要という話をしましたが、システム開発をするとき意識してますか？

正直、開発プロジェクトでは「プロジェクトの目的と背景」をはっきりさせておくことが超重要です。

ただ、これができるエンジニアってすごい少ないんですよね…

この少なさ、つまり希少性は年収となって表れています。

そのあたりのことをこちらの記事でまとめてみたので、興味がある方はぜひ読んでみてくださいー

関連記事SEで年収1000万まであげる戦略を転職とか含めて考えてみた

2021.06.20

それでは！