コラム｜設計書は、書くことより、どこを参照させるか。それもまた設計です

「親切に全部書いた」は、必ずしも良い設計書ではありません。

設計書では、同じ内容をあちこちに書かずに「○○を参照」とすることが大切です。

同じ説明を複数箇所に書くと、修正のたびに全て直さなければなりません。修正漏れが起きれば、設計書の内容に矛盾が生まれてしまいます。

参照先を一つにまとめておけば、修正も一箇所で済みます。設計書の一貫性が保たれ、保守もしやすくなります。

また、後任者にとってもメリットがあります。情報が整理されているため、どこを見ればよいかが分かりやすく、全体像も把握しやすくなります。

ただし、「○○を参照」を多用しすぎるのも考えものです。参照をたどる回数が増えると、かえって読みづらくなります。

大切なのはバランスです。

重複は減らしつつ、重要な内容はその場で説明する。設計書もまた、読み手への思いやりが大切なのだと思います。

書くことより、どこを参照させるか。その設計もまた設計です。