設計書を書くときに気をつけること

こんにちは。土居です。最近はとても久しぶりにウォータフォール開発のプロジェクトに携わっています。そこで学んだ設計書を書く際に気をつけるべき点を整理したいと思います。

気をつけるべき点

主語の明確化

設計文章の主語を明確にしましょう。よく読めば自明だろうという箇所であっても、特に複数の事業者・システムから利用される環境の設計をしている場合には主語を正確にしないと、誤解や混乱を招く可能性があります。

パラメータは設計思想を記載

パラメータや設定項目について設計の思想や、選択した理由を記載しましょう。例えば詳細設計でAWSリソース等のパラメータをただ列挙しているだけだと、読み手になぜそのパラメータを選択しているのかが伝わりません。ただ、全てのパラメータについて詳細に記載する必要はないでしょう。AWSリソースには多くのケースでデフォルトで構わない物やオプション項目もあり、特にEC2やRDSのパラメータグループの様に設定項目が多い場合には全て記載するのは現実的ではありません。特にポイントとなるパラメータや、あえてこの選択をしている、といったものに絞って説明するだけでも効果があるでしょう。

曖昧な記載はできるだけ避ける

ついやってしまいますが、「必要に応じて〜する」、「重要な時は〜する」といった曖昧な表現に逃げてしまうことがあります。どの様な時に必要になるのか、なぜ重要なのかははっきり記載すべきです。設計に自信が無い場合、このような曖昧な表現を使ってしまうことがあるかもしれません。明確に記載することで、設計の質が向上します。

目的を初めに具体的に記載する

設計書に作業内容を記載する際には、何を目的とした作業かを初めに示すことで理解しやすくなります。

第三者観点でわかりやすく記載

設計書は今後、思ったよりも範囲の広い人に読まれます。特にAWSを利用したシステムの設計書はサービス名や設定項目等、専門用語が多くなりがちなので、脚注などで説明を加えるとわかりやすくなります。時には専門用語をあえて使わず、より一般的な言葉に置き換えても良いかもしれません。

体裁

タイトル・見出し・本文毎のフォントや文字の大きさ、また章・節・項番といった構成は文書間で必ず統一します。可能であれば、サンプルや他プロジェクトの同等の文書を参考にするのも有効です。また、設計書を機能毎に分けて別冊とする様な場合に、文書によって同じ意味の言葉が異なる表現となってしまうことがあります。これは用語集を作るなどし、統一しましょう。

外部文書の参照

使用するクラウドサービスプロバイダーの公式ドキュメントや、統一の基準となる標準仕様書等の文書を参照にする場合には正確な文書名 + 版数、発出元、年月日を忘れずに記載しましょう。版数によって大きく内容が更新されることもあるため、どのタイミングの情報をもとに設計しているかを確定させる必要があります。

簡潔な記載

設計書はできるだけ簡潔にまとめましょう。例えば使用するクラウドサービスの仕様など、変更ができない条件については詳細に説明する必要はありません。まずは、実装に必須な情報のみを記載し、その後、必要に応じて詳細を追加する程度で十分です。この方法で、読み手にとって無駄がなく、理解しやすい設計書になります。

まとめ

設計書はプロジェクトの成功を支える重要なドキュメントです。主語の明確化や、パラメータ選定の背景説明、曖昧な表現の排除といったポイントを意識することで、誰が読んでも理解しやすく、役立つ設計書を作成できます。また、文書全体の体裁を整え、外部参照文書の情報を正確に記載することで、設計書の信頼性も向上します。これらのポイントを押さえて、より良い設計書を作成していきましょう。

どいけん