要求の表現の難しさ
【改訂第２版】［入門＋実践］要求を仕様化する技術・表現する技術 仕様が書けていますか？の6.2.1より。
「ソースコードなら書けるが、文章にするのは苦手で…」
設計仕様書を書くことの難しさ
上記書籍では、要求を仕様化、表現することを一冊かけて説明しています。要求を明確にすることは、本１冊になるほど難しいことです。そして、仮に要求を明確にできたとしても、次にそれを実装できるレベルまで（詳細）設計することもまた、難しいです。それは、設計段階においても、同様に「ソースコードなら書けるが、文章にするのは苦手で…」という話が出るためです。つまり、訓練無しに、制御思想や設計理由を日本語で表現することは難しいのです。
現場であったこと
私が設計書をレビューした時に、その仕様書は日本語として成立していない文で表現されており、設計の妥当性を評価する以前のレベルだったときがありました。そのため、その時は逐一表現内容の整合を確認し、正しい日本語へ修正した上で、設計内容をレビューすることになりました。具体的な問題としては、主語や目的語が不明、体言止めによる表現の曖昧さ、多数の誤字と誤記（スペルミス、変換ミス、不要文字、参照箇所誤）などがありました。
なぜ、低品質な設計書が出来上がったのか
1. 作成者が日本語で表現することの難しさを認識していない。
2. 作成者が読み手を想定して設計書を作成していない。
3. レビューのプロセスが確立していない。
現場であった問題の直接な原因は要因1だと考えています。そこで、設計書をセルフチェックするためのイメージ図を作成しました。
設計書セルフチェックのイメージ図
設計書セルフチェックのイメージ図を作成してみましたが、チーム全体で設計書の読み手を共有すること、レビュー時の確認ポイントを明確にすること、などでも設計書の品質向上はできると思われます。チームとしての設計書作成レベルを向上させる方法を今後も考えていきます。
追記：
「エンジニア歴20数年の私が、設計書を書く際に心がけていること」の記事は素晴らしいと思います。
