はじめに

時の経つのは早いもので、私がIT業界に身を置いて四半世紀になってしまいました。

その間、膨大な数の「設計書（仕様書）」を書いて来ましたが、未だに悩み・迷いは尽きません。
それでも、亀の甲より年の劫とも申しますので、私なりの経験則を「個人」と「チーム」の両観点でまとめてみました。

• 本稿で前提とする設計書は、ExcelやWordで書かれた、フォーマルな設計文書、です。
• したがって、自社サービス開発よりも受託開発、アジャイルよりもウォーターフォール、を前提として読んでいただいた方が、しっくりくると思われます。
• とはいえ、「個人的に心がけていること」の章は、どんなシチュエーションであれ通用すると考えます。

＜ご注意＞
本稿の内容は執筆者独自の見解であり、所属企業における立場、戦略、意見を代表するものではありません。

個人的に心がけていること

当該文書の作成目的を文頭に宣言する

• 「本書では◯◯機能の仕様について記載する」とか、そんな感じで。

まず初めに章立てを考える

• 章立てを考えることは、設計書を設計すること、といえます。
• できれば、章の見出しだけを書いた状態で然るべき人に見てもらうと、根本的な認識ズレのリスクが減らせます。
• 章の冒頭にも「本章では××の仕様について記載する」と書いておくと、読み手にとって分かりやすいと思います。

全体像を示す → 詳細を説明する、の順番で

• これは設計書でもプレゼンでも、どんな文書でも同じだと思います。

一行あたりの文字数を40文字以内にする

• 人間は、一行あたりの文字数が全角40文字を越えると、読みづらく感じるそうです。
• A4横の書式で、横にながーい文章を書く人がいますが、私はとても読みづらいです。

一文を短くする

• 一文が何行にも渡る文は、とても読みづらいです。
• 一文二行以内が良いと思います。上記の通り、一行あたりの文字数を40文字とすると、一文80文字以内です。

箇条書きを使う

• 箇条書きにすると、一文が短くなり読みやすくなります。

図を使う

• 人間は文字よりも図の方が直感的に理解できます。
• 特に全体像を示す際には図は文字よりも雄弁です。

表を使う

• これは障害を防止する上で大変重要な意味があります。
• 複雑な条件を文字だけで定義しようとすると、読み手に誤解を与えます。

インデント（字下げ）を使う

• インデントは、読み手に対して文章構成を視覚的に理解してもらうための、効果的な手法です。

主語を統一する

• 「◯◯ボタンをクリックされた場合、××画面を表示する」と「◯◯ボタンをクリックした場合、××画面が表示される」では、主語が違います。
• 設計書では通常「システム」か「ユーザー」、どちらかが主語かと思います。どっちじゃないと絶対ダメということはないと思いますが、少なくとも文書内で統一しましょう。
• ちなみに私は設計書では基本的に「システム」を主語にするようにしています。

用語を統一する

• 同じ機能、同じ概念は、一言一句同じ用語を使いましょう。同じことを別の用語で記載しないようにしましょう。
  • 例：「日締め」「日次締め」「日締処理」
• プロジェクト内で用語集を作りましょう。
• 略語についても用語集に記載するか、または文書冒頭に「Ruby on Rails（以下、RoRと記載）」という感じで書きましょう。（「IT」など一般に浸透している略語を除く）

造語をしない

• 良くありがちなのが日付関連です。
  • 「実行日」「処理日」「当日」…　
    • どこから取得するのですか？時刻を含みますか？タイムゾーンは？暦とズレる場合はありますか？
• プロジェクト内で共通の概念であれば、用語集に定義を記載しましょう。
• 当該文書内に閉じた概念で、自分で作り出した用語であれば、その定義の項を作り、明確に記載しましょう。

表記ゆれを排除する

例：

• 「サーバ」と「サーバー」
• 「Web」と「ウェブ」
• 「4月」と「４月」と「四月」
• 「です・ます」と「だ・である」

固有名詞は正確に

• 例えば、「JAVA」は誤記、正しくは「Java」。
• プロダクト名や企業名については勘違いして覚えていることが多いので、大文字小文字、単語間の空白の有無など、キチンと調べて正確に書きましょう。

チームをリードする際に心がけていること

私は、設計書の良し悪しに影響するのは、個人の努力や心がけよりも、チームとしての取り組みの方が大きいと思っています。

チーム全体として、設計書の書き方に統一感がないと、第三者にとっては設計書全体の価値が低く見えてしまいます。

記載粒度の認識を合わせておく

• 基本設計書と詳細設計書で、どちらに何をどこまで書くか、みたいなことです。
• 必要以上に細かく書きすぎると、メンテナンスが追いつかなくなり、結果として誰も設計書を見なくなります。

章立ての記載方法を合わせておく

あくまでも一例ですが、
１．ｘｘｘ
　１．１．ｘｘｘ
　　１．１．１．ｘｘｘ
　　　（１）ｘｘｘ
全角／半角どちらにするのか、インデントするのか否かも含めて、細かく決めておくと良いです。

設計書を量産する前にサンプルを作っておく

• 設計書のレビューアーとなるエンジニアがサンプルを作ると良いです。
• サンプルを作ったら、「見ておいてね」だけではなく、どのように書いて欲しいのか、サンプル作成者の想いを全員に説明する場があると良いです。

テンプレートはなるべくシンプルに

• 罫線の引き過ぎは生産性を落とします。
• 型にはめようとしすぎると内容が薄くなります。フリーフォーマットの方が適切に表現できる場合もあります。
• 確かに体裁も品質の一部であり大切ですが、バランスのとれたテンプレートを作りましょう。

変更履歴の残し方について決めておく

• 赤→青→緑→…と、変更が入るたびにカラフルにしていくメンバーがいたり
• それに対して「読みづらい！」と文句を言うメンバーが出て来たり（それは私）
• Excelから脱却して、Markdownとかにして、バージョン管理システムに入れるのが良いのでしょうが…（政治的な要素もあったりして）なかなか難しい。
• 変更履歴シートを作って、どのシートのどの箇所をどのように直したか記載するのが現実的な落とし所でしょうか。

以上のような事項をガイドとしてまとめておく

• レビューがスムーズ
• メンバーが入れ替わった際に説明がスムーズ
• どんなに忙しくてもガイドのメンテナンスをサボるべからず

まとめ

• 文章書きの上達のためには、訓練しかありません。
• 一番大事なのは、身近に厳しく添削してくれる方がいること、だったりします。

ということで、この文書に至らない点がございましたら、コメント等でお知らせください！