ソフトウエア開発に関する一私見〜ドキュメントの要否（Ｖ字モデルの左側）〜

2024年11月13日 18:27

こまさです。
今回は、設計時のドキュメントについてです。
ドキュメントについては下記の通りに別の記事も書いていますが、今回は“ソフトウエア開発に関する一私見”に沿って、私の方法についてです。

設計ドキュメントは何のために書くのか

皆さんは、何のために設計ドキュメントを書いていますか？
それぞれの所属している組織や立場によって、理由はさまざまだと思います。

積極的には書きたくないが、書かないと上司から叱られる。
納品物に含まれているため、仕方なく書く。
「設計書」と名のつくドキュメントがないと社内のQMS上、プロジェクトの体裁が整わない。

いずれにせよ、書きたくて書くわけではなく、書くことによるベネフィットを期待しているわけでもないことが多いのではないでしょうか。
私は、“設計書”や“検討書”などの“〇〇書”を書くことが大好きになりました。若い頃は嫌いでしたが、今では楽しんで書いています。
※今の書かない人たちと同じだったかもしれません。
私が“設計ドキュメント”を書く主な目的は次の二つです。

検討中の考えを客観的に評価し、間違いがないことを確認して自己承認するため。
自分の考えやアイデアを共有し、承認してもらうため。

ある意味、自分の承認欲求を満たすためなので、決して褒められるものではないですが、結果としてソフトウェア開発の役に立っているので良しとしています。
職業としてソフトウェア開発をしているのであれば、ドキュメントは避けて通れないものだと思います。ならば、自分の目的を一度客観的に考え、意味のあるドキュメントとなるように再定義するのも良いかと思います。

設計ドキュメントの種類

設計ドキュメントにはどの様な種類があるでしょう。記述する内容で分けると、おおよそ次の様になると思っています。
・ソフトウェアの構造やロジックなどの検討経過を書いたドキュメント
・ソフトウェアの構造を書いたドキュメント
・ソフトウェアの処理を書いたドキュメント
私は、これらのドキュメントをそれぞれ
・〇〇検討書
・〇〇アーキテクチャ設計書
・〇〇詳細設計書
と呼び分けています。
何をどこまで書くかは、プロジェクトの規模や特性により増減しますがドキュメントの意味付けは変えません。
また文書量が少ない場合には「〇〇アーキテクチャ設計書」と「〇〇詳細設計書」を同一ドキュメント内の章とする様にしています。

コーディングの際にはこれらドキュメントを正として進めます。万が一、コーディングや動作に支障が出る場合にはドキュメントの改修を先にします。
ドキュメント改修🟰再設計する事は忘れないでくださいね。

ドキュメントを書くツール

ドキュメントを書くツールにはたくさんの種類があります。それぞれに得意不得意がありますので、書きたいドキュメントの特性に合わせれば良いと思います。
ただ、次の点については充分な注意を払ってください。どれかが欠落もしくは弱いとドキュメントのメンテナンス。つまり、常に最新に保つ活動が損なわれてしまいます。
それでは使うことが出来ないドキュメントとなってしまいます。

ドキュメントの修正に苦労するか否か
版数管理で変更点を容易に知り得るか否か
ツールの習得が容易か否か
外部の組織との共有に支障があるか否か