設計書における文章の重要性
設計書は、システムの要件定義、機能設計、データベース設計など、開発に必要な情報をまとめたドキュメントです。開発チームだけでなく、顧客や関係部署との情報共有にも利用されるため、その内容が正確かつ分かりやすく記述されていることは非常に重要です。
文章の書き方によって誤解が生まれ、仕様が曖昧になってしまったりしますし、これが原因でシステム障害が発生したりすることもザラにあります。特に要件定義書や基本設計書は顧客との擦り合わせが必要なドキュメントになるため、これらを作成する工程に携わるエンジニアは、ドキュメンテーションのスキルが大きく求められることになるわけです。
はじめに
システム開発において、設計書はプログラムの基礎となる重要なドキュメントであり、システムの品質に大きく影響するものです。例えば設計書の記載から仕様を読み取れなければコーディングの遅れが発生しますし、試験シナリオ作成者が設計書を読み違えた結果、誤った試験シナリオが生まれてしまう原因にもなります。
当然、システムエンジニアとして働いている方のほとんどはこれを理解しているわけですが、それでもエンジニアの中にはドキュメントの執筆が苦手な方が一定数いるのも事実です。
とはいえ、もちろんドキュメンテーションが全てではありません。本当に優れた技術力を持っていれば、ドキュメンテーションが苦手でも活躍できますし、評価もされるでしょう。ですが、これは極めて稀な例だと思います。
例として、プログラマとして開発工程～結合試験工程までプロジェクトに参画したとしましょう。
この限られた工程の中であっても、単体テストの仕様書や、バグがあった際に起票するバグ票など、書かなければならないドキュメントが多く存在します。これらのドキュメントが上手く書けない場合、管理者のレビュー工数がかさみますし、バグ票も起票者から事象を聞いた別の担当者が校正する、といったことが発生します。
若手ならちょっと指導されるくらいで済むでしょう。ですが、年次が高いエンジニアはそうもいきません。間違いなく「この年次でまともな文章が書けないのか」という見方をされます。
悲しいことにこれが日本のエンジニア業界の現実です。プログラムができることより、テキストや対面でのコミュニケーションが円滑に行えるか、が評価の大部分を占めるのです。
私がこれまで出会ったきた技術力の高いエンジニアは、自身の書いたプログラムをどういう思想で、どういう挙動を想定してコーディングしたかを正しく伝えることができますし、バグに対してどういう理由で、どういう修正を行ったかの説明ができたのです。だから彼らは一緒に働く人々から「すごい技術力を持ったエンジニアだ」と認知されていますし、評価もされていました。
どれだけすごいスキルを持っていようが、それを伝える能力がなければ、周りも評価ができないのです。ドキュメンテーションは自身の評価を上げるために必須である、という認識を持ってもらえればと思います。
この記事で伝えたいこと
この記事では、開発プロジェクトにおけるドキュメンテーションの向上に焦点を当て、誤解を防ぐための文章表現やルールを紹介していきます。具体例やサンプルを交えながら、分かりやすく解説することで、設計書の作成・レビューに携わるエンジニアの方々が、より質の高いドキュメントを作成できるようになればと思っています。
本来エンジニアは技術力で勝負し、技術力で評価されるべきだと思っています。ですが、ドキュメンテーション力がないと評価が下がってしまうのも事実です。
これを書いている私自身もまだまだ探りさぐりではありますが、それでも一応10年以上システム開発に携わり、ドキュメントを書き続けている身です。多少のこだわりはあります。
ぜひ最後まで読んでいただければと思います。
設計書の役割と目的
設計書には以下のような役割と目的があります。また、一般的には、参画人数が多く開発規模が大きいプロジェクトになるほど、設計書の役割も大きなものになります。
システムの要件を明確にする
顧客や関係部署とシステムに関する共通認識を形成し、誤解を防ぐ役割があります。ドキュメンテーション不良があると、再度顧客との調整が必要なのはもちろん、他の工程のドキュメントへの影響も出てしまうなど、工数への影響が大きくなります。なので、特に上流工程におけるドキュメンテーションは慎重に、丁寧に行うことが求められます。
保守・運用のための資料となる
システムの構成や動作に関する情報を記録し、将来の保守や運用を円滑に進める役割があります。特に障害発生時のリカバリを早急に行うためには、設計書や運用手順書などのドキュメントが整っていることが非常に重要です。逆にここが整っていなければ、障害対応が後手後手になり、顧客評価を下げることにも繋がりかねません。
システムの履歴を記録する
開発の過程で変更された内容を記録し、システムの変更履歴を管理する役割があります。いつ修正が行われたのか、どんな起因で修正が行われたかをプログラムのみから追うのは困難です。変更履歴をしっかり分かりやすく残すのも、ドキュメンテーションで意識すべきポイントです。
たまに現場でも変更履歴を雑に残す人がいます。見ている人はしっかり見ているので気をつけましょう。
読みやすい設計書がもたらすメリット
設計書は開発プロジェクトを成功に導くための重要な基盤となるドキュメントです。読みやすい設計書を作成することで、開発チームの理解度向上、コミュニケーションの円滑化、保守・運用の効率化など、さまざまなメリットが期待できます。
開発チームの理解度向上
設計書の内容が理解しやすいことで、開発期間の短縮や品質向上に繋がります。また、上流工程のドキュメントがしっかりしていることで安心感が生まれる場合もあるでしょう。
逆に、開発する人間から見て仕様不備がいくつも見つかるようでは、プロジェクト内の信頼関係も揺らいでしまいますし、修正工数もかかります。
これを書いているのは11月、空気も乾燥してきましたね。
コミュニケーションの円滑化
顧客や関係部署との情報共有がスムーズになり、誤解やトラブルを減らすことができます。
規模の大きいプロジェクトだと、対面で仕様の質問をするのも一苦労だったりするので、ドキュメンテーション力＝コミュニケーション能力だと言っても過言ではありません。
保守・運用の効率化
設計書の内容が分かりやすいため、保守・運用担当者がシステムを理解しやすく、作業効率が向上します。
特に障害発生時は全てにおいてスピードが求められ、障害報告、修正方針などでドキュメンテーションが求められます。この際、インプットとなる設計書の記載が曖昧だったりした場合、顧客との調整が難航することになります。もちろん障害発生した機能のリトライも地獄です。
開発リスクの低減
設計書の誤りや曖昧な表現によるミスを減らし、開発リスクを低減できます。
開発現場でよくある障害原因の一つとして「仕様誤認」というものがあります。仕様誤認は明確にドキュメンテーションの不備が根本原因となるものです。これが多く発生しているプロジェクトは、動くシステムはできたが、顧客の要望にそぐわないシステムになっている可能性が高いです。
設計書における文章の基本ルール
ここからはドキュメントを作成する際の基本ルールを紹介していきます。
以下が基本的なルールを箇条書きにしたものです。
- 簡潔で分かりやすい文章にする
- 曖昧な表現を避ける
- 一文を短くする
- 図表を効果的に活用する
- 用語の定義と統一
次にそれぞれについて深堀りしていこうと思います。
簡潔で分かりやすい記載にする
設計書はシステムに関する情報を正確に伝えるためのドキュメントです。そのため、複雑な表現や回りくどい言い回しは避け、簡潔で分かりやすい文章を心がけることが重要です。
例えば、
「本システムは、顧客情報を入力するための顧客情報入力画面と、顧客情報を検索するための顧客情報検索画面から構成される」
という文章よりも、
「本システムは、顧客情報入力画面と、顧客情報検索画面で構成される」
という文章の方が、より簡潔で分かりやすいです。
曖昧な表現を避ける
曖昧な表現や誤解を招く表現は、設計書の品質を低下させ、開発工程に支障をきたす可能性があります。以下のような表現は避けるようにしましょう。
- 「おそらく」「たぶん」などの推測表現
- 「など」「等」などの曖昧な表現
- 文脈によっては複数の解釈が可能な表現
例えば、
「顧客情報の更新は、契約者住所の変更などがあった場合に実施する」
という文章よりも、
「顧客情報の更新は、契約者住所の変更または連絡先電話番号の変更があった際に実施する」
という文章の方が、より明確で誤解を招きにくい表現です。「など」の使用は例を示したい場合に留めましょう。
また、
「予期せぬ動作があった場合、処理をエラー終了する」
のような文章も良くないですね。「予期せぬ動作」の解釈が人によって変わってしまいます。
「検索処理中に例外が発生した際、処理をエラー終了する」
とした方が、具体性があり正確に伝わります。
一文を短くする
一文が長くなってしまうと「その文章において伝えたいことは何か」がブレてしまいます。なので適度に句点を入れて文章を閉じたり、改行を行ったりして一文を短くするよう心がけましょう。
それに加え、長い文章は読まれにくいと言うのもあります。特にTeamのチャットとか、他チームとのQAとかでなかなか回答が返って来ない方、一度文章の長さを見直してみましょう。また、一度で終わらない内容であれば、複数回やりとりをすることを前提として文章を組み立てたりすると、スムーズなやりとりができるはずです。
設計書における図表の活用
文章だけではどうしても表現が難しく、伝わりづらいこともあります。こういう場合は図や表を用いて表現するようにしましょう。少し長くなりそうなので、下記「設計書における図表の活用」で別解します。
用語の定義と統一
設計書ではシステムに関する専門用語が多く登場します。プロジェクトの混乱を防ぐため、これらの用語を定義し、設計書全体で統一して使用することが重要です。
専門用語を定義する際には、以下のような点を意識し用語集を作成すると良いでしょう。
- 用語の意味を明確にする：用語の定義を簡潔かつ正確に示す
- 関連する用語との違いを明確にする：似たような用語がある場合は、その違いを明確に示す
- 図表などを活用する：用語の意味を分かりやすく説明するために、図表などを活用する
また、長い単語が用語となっている場合、プロジェクトによっては略語が設けられることもあります。こちらについても用語集に併せて記載しておくことをお勧めします。
文章表現のポイント
設計書では、正確で分かりやすい文章表現が求められます。以下に、具体的な文章表現のポイントを紹介します。
受動態を避ける
設計書は自機能が主語になるように書くのが大前提です。
その上で受動態を利用すると、文章を分かりにくくする原因となります。能動態で表現できる場合は、能動態で記述するようにしましょう。
受動態）ユーザの年齢は、生年月日と現在日付から算出される
能動態）ユーザの年齢は、生年月日と現在日付から算出する
受動態を利用した文章は「年齢の算出を別の機能で行っている」印象を受けると思います。それに対して、能動態を利用した文章は「年齢の算出を自機能で行っている」印象を受けると思います。
このように、年齢を算出するロジックを有した機能において受動態を利用してしまうと、読み手に誤解を与える原因になります。
なお、受動態を利用する際は「別システムから連携された顧客情報を、顧客テーブルに取り込む」のように、受動態部の主語が明確になるようにします。
上記の例で「別システム」の部分を削ってしまった場合、「顧客情報はどこからやって来たの？」となってしまいますよね。結構やりがちなので気をつけるようにしましょう。
主語と述語を明確にする
文章の主語と述語を明確にすることで、読者は文章の内容を把握しやすくなります。主語と述語が不明確な文章は、誤解を生む可能性が高いため注意が必要です。
例えば、
「入力した顧客情報を、データベースに保存する」
という文章は、誰が顧客情報を入力するのかが明確ではありません。
「ユーザが入力した顧客情報を、データベースに保存する」
と主語を明確にすることで、どんな機能なのかが伝わりやすくなります。
接続詞を適切に使う
接続詞は、文と文を繋ぐ役割を果たします。接続詞を適切に使うことで、文章の流れをスムーズにし、読者の理解を助けることができます。個人的な印象ですが、エンジニアの書く文章は特にこの接続詞が欠けているため、読みづらくなっているケースが多いです。
例えば、
「ユーザが入力した顧客情報を登録する。顧客情報は検索画面から照会可能とする。」
という文章があったとします。これは関連のある2つの文章が句点で分かれている例ですが、接続詞がないことにより、2つの文章が途中で切れている印象を受けると思います。
これを
「ユーザが入力した顧客情報を登録する。また、顧客情報は検索画面から照会可能とする。」
とすることにより、句点で分かれた2つの文章の関連性を示すことができます。
音に出して読みづらい文章を避ける
音に出して読みづらい文章は
- どこで区切って読めばいいか分からない
- 同じ音が何回も続く
などが挙げられます。
まずは「どこで区切って読めばいいか分からない」文章について見ていきましょう。
例）彼は新しいプロジェクトのために準備をしていたが実際に始めてみると様々な問題が発生し思った以上に難しかったためチームメンバーの協力が不可欠であると感じた。
長めの文章ですが、句読点がないためどこで区切って読むのかが分かりづらいです。このような場合、句読点を適切に入れることで、読みやすい文章になります。
改善案）彼は新しいプロジェクトのために準備をしていたが、実際に始めてみると様々な問題が発生した。思った以上に難しかったため、チームメンバーの協力が不可欠であると感じた。
続いて「同じ音が何回も続く」文章を見てみましょう。
例）この計画が確かに可能かどうか考えなければならない。
「か」の音が連続することで、音に出して読みづらい文章になっていると思います。この場合は、意味が同じ単語で言い換えることで改善します。
改善案）この計画の実現可能性を検討する必要がある。
音読しづらい文章は黙読もしづらい。どちらも文章を読み上げることには変わりありませんからね。
書いている際には気が付きづらい部分なので、誰かに説明してみるなり、自分で読んでみるなりしてブラッシュアップしていくようにしましょう。
設計書における図表の活用
設計書では、文章だけでなく図表を効果的に活用することで、より分かりやすく、理解しやすい内容にすることができます。また、文章では表現しづらい部分が、図表だと表現しやすくなったりします。
分かりやすい設計書に、図表の使用はマストです。
図表の役割と効果
図表を活用することで、以下のような効果が期待できます。
- 複雑な内容を分かりやすく表現する
- 全体像を把握しやすくする
- 理解を促進する
- 記憶に残りやすくする
図の作成例
文章だけでは登場する要素の関係性が分かりづらい時や、処理の流れが分かりづらい場合は、図を用いて説明を行うとわかりやすくなります。
ここでは例として
「画面で入力したクレジットカードの情報を、別システムを介してトークン化する。そしてトークン化したクレジットカード情報で決済処理を実施する」
機能を図にしてみたいと思います。
クオリティはさておき、登場する要素と処理の流れは伝わりやすくなったかと思います。
本筋とはあまり関係ないですが、上の例はクレジットカード情報の非保持化ですね。身に覚えのあるエンジニアは多いはず！
表の作成例
処理の条件が複雑な場合や、組み合わせが多い場合には表を用いると分かりやすくなります。
例として「顧客情報の検索条件はユーザID、顧客氏名と契約状態とし、ユーザIDを指定した際は顧客氏名、契約状態の入力は不可とする。なお顧客氏名と契約状態については双方入力可能とする」という機能の入力パターンを表にしてみます。
各要素と、それぞれの入力パターンが分かりやすくなったのではないでしょうか。
図表と文章の相互補完
図表は文章を補完する役割を果たし、文章は図表を補完する役割を果たします。図表と文章を相互補完させることで、より分かりやすく、理解しやすい設計書を作成することができます。
図表を利用する場合は、どんなことを示した図表であるのかを文章で説明するようにしましょう。
図がメインとなる設計書
設計書の中には図をメインとした設計書も存在します。以下に例を紹介します。
| 図表の種類 | 説明 | 使用例 |
|---|---|---|
| システム構成図 | システムを構成する要素とその関係性を図示する | ハードウェア、ソフトウェア、ネットワークなどの構成要素を示す |
| データフロー図 | データの流れを図示する | システムへの入力データ、処理、出力データの流れを示す |
| クラス図 | システムを構成するクラスとその関係性を図示する | オブジェクト指向設計におけるクラス間の関係を示す |
| ER図 | データベースを構成するエンティティとリレーションシップを図示する | データベースのテーブル構造を示す |
この他にも開発現場では様々な図や表が登場します。文章と図表の良い部分を理解して上手く使い分けることを心がけましょう。
設計書のレビュー
設計書のレビューは要件に沿った設計となっているかが最も重要なことですが、それだけではなく顧客に必要な情報が正しく伝わるか、開発チームが仕様誤認しないような記述となっているか、など様々な観点があります。
設計書レビューで見られる観点
設計書のレビューでは、以下のような観点で指摘されることが多いです。基本的にはこれまで挙げてきた設計書の記載ポイントと同じようなことですね。
- 文章が分かりにくい：専門用語の乱用、曖昧な表現、冗長な文章など
- 図表が分かりにくい：タイトルや凡例が不足している、図表と文章の連携が不足しているなど
- 用語が統一されていない：同じ用語に対して、複数の表記が使われているなど
- 必要な情報が不足している：機能の詳細、処理手順、データ構造などが不足しているなど
- 情報が矛盾している：文章と図表の内容が矛盾している、異なる箇所で記述内容が異なるなど
設計書のレビュー前にしておきたいこと
設計書の作成において「ここの記載、これで意味が伝わるだろうか」や「この処理で考慮すべき点が漏れていないだろうか」など、悩むことは多いはず。こういった懸念が発生した場合、レビューの前にできるだけクリアにしておきたいです。
個人的にお勧めなのは、同じ作業を実施している人とクロスで設計書のチェックをすることです。
設計書を書いた本人は処理を理解した上で執筆しているため、しっかりと書いたつもりでも、必要な情報が抜けていたり、説明がアバウトだったりすることが多々あります。自分以外の人に設計書を読んでもらうことで、自身では気が付けなかったミスなどを拾うことができます。
設計書のレビュアーとなる人は、打ち合わせなどで時間が取れないことが多いです。そういった点も考慮し、レビューイ側である担当者同士が協力してクオリティの向上に努めましょう。
さらに、設計書に関する書籍やWebサイトなども参考になるでしょう。悩みの内容が明確であるならば、Google検索などで調べた方が早い場合もあるはずです。また、ChatGPTなどのAIに聞いてみるという方法もあります。設計書の書き方のような普遍的なテーマであればAIでも十分な回答が期待できるしょう。
レビュー前に適切な準備をすることで本番がスムーズに進みますし、予定より早く終わればそのぶん別の作業に時間を使うことができます。金曜日であればプレミアムフライデーで早退しちゃってもいいでしょう。もっとも、プレミアムフライデー自体が早退してしまっているんですけどね。
何事も準備が大事です。お前もだぞ、プレミアムフライデー。
一番重要なのは、読んでいる相手の気持ちを考えること
この記事では、設計書における文章の重要性、文章のルール、具体的な文章例、図表の活用などを解説してきました。ですが、最も重要なことをこれまで言っていませんでした。
それは読んでいる相手の気持ちを考えることです。
我々は自分に向けてドキュメントを作成している訳ではありません。自分以外の人にドキュメントを作成しているのです。読んでいる相手のことを常に考えていれば、分かりづらいドキュメントを作成しようとは思わないはずです。
もちろん、スキルの問題も少なからずあるでしょう。この記事はそういった方が、相手が読みやすい文章を書けるようになれれば良いなと思いもあり執筆しています。
一緒に働いている人が気分良く快適に仕事ができるように、思いやりのあるドキュメンテーションを心がけていきましょう。
最後に
結局のところ、最後に行き着くのは道徳。本当に学んだか？ガンジーへの冒涜。ここまで読んでくれてサンクス。