エンジニア歴20数年の私が、設計書を書く際に心がけていること

はじめに

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

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

• 本稿のテーマは、「主に設計書を想定した、開発ドキュメントの書き方」です。
• 本稿で前提とする設計書は、ExcelやWordで書かれた、フォーマルな（≒納品物になりえる）設計文書、です。
• したがって、自社サービス開発よりも受託開発、アジャイルよりもウォーターフォール、を前提として読んでいただいた方が、しっくりくると思われます。

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

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

当該文書の作成目的や位置付けを冒頭に記載する

• 「本書では◯◯機能における××画面のレイアウト設計および入出力設計について記載する」とか、そんな感じです。
• もし関連文書があれば、「△△については□□を参照」と書いておくと良いです。
• 上は特に、設計フェーズよりも後々（例えばシステムテストや、保守や、機能追加時）に設計書を"漁る"場面で有効です。

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

• 章立てを考えることは、設計書を設計すること、といえます。
• できれば、章の見出しだけを書いた状態で然るべき人に見てもらうと、根本的な認識ズレのリスクが減らせます。

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

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

一行あたりの文字数に気を配る

• A4横の書式で、横にながーい文章を書く人がいますが、私はとても読みづらいです。
• 一行あたりの文字数の最適解
  • ググると、横書きの場合は30〜35文字を勧めているWeb記事が多いようでした。
  • **私の中では、設計書では40文字までということにしています。**読みやすさと、1ページあたりの情報量とのバランスです。
    • 40文字に確たる根拠はないです。でも、「一行80バイト」というとピンと来る方もいるのでは…
  • 文字数は各個人の基準でよろしいかと思います。要は「気を配るべき」という主旨です。

一文を短くする

• 長い文は、構造が複雑になりがちで、誤解を生むリスクが高まります。
• 個人的には「一文二行以内（つまり80文字以内）」を目安にしています。三行に渡ってしまう文は、分解できないか検討しています。

箇条書きを使う

• 項目の列挙によって長くなる文は、大抵は箇条書きに変換できます。
• 構造が複雑な文を分解する際にも、箇条書きが有効な場合が多いです。

図を使う

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

表を使う

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

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

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

主語を統一する

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

用語を統一する

• 同じ機能、同じ概念は、一言一句同じ用語を使いましょう。同じことを別の用語で記載しないようにしましょう。
  • 例：「日締め」「日次締め」「日締処理」
• 些細なことのようですが、システム開発においては、担当者間の些細な認識のズレが大問題を引き起こすことが多々あります。
• プロジェクト内で用語集を作りましょう。
• 略語についても用語集に記載するか、または文書冒頭に「Ruby on Rails（以下、RoRと記載）」という感じで書きましょう。（「IT」など一般に浸透している略語を除く）

造語をしない

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

表記ゆれを排除する

例：

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

自分専用のメモであれば、こんな些細なことを気にする必要はないのです。
しかし私は、読み手がいる以上、「こういうことで文書の良し悪しを判断する人がいるかもしれない」と考えた方が無難であると思います。

固有名詞は正確に

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

まとめ

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

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

（2018年2月15日追記）

多くのフィードバックをいただき、誠にありがとうございます。

あくまで私個人の経験則に基づく記事ですので、過不足・思慮不足はあるかと思います。
皆様の開発現場に合うように改編していただき、ご活用ください。

私は、教育やガイドによって「設計書の書き方」をチーム内で合わせておくことで、設計レビューにおいて「設計そのもの」に注力できるようになれば良いな、と考えています。

（2018年3月11日追記）

「一行あたりの文字数〜」、「一文を短くする」、「箇条書きを使う」について、表現を見直しました。
主旨は変わっておりません。