結論から言うと、
「詳細設計は必要、詳細設計書も必要」
と考えている。
ただ、コスパの良い詳細設計書の書き方は見つかっていない。
作る上では考えているのにアウトプットができないとはこれいかに。
詳細設計書とは
ウォーターフォール型の開発だとこのようなドキュメントが作られる。
- 要件定義書
- クライアントと話して何が必要なのかをまとめたもの
- 基本（外部）設計書
- 要件定義書をもとに画面や機能を詳細化したもの
- 詳細（内部）設計書
- 基本設計書をもとに各画面、各機能を具体化したもの
- これをもとにコードが書かれる
- 単体試験仕様書
- 実装した各画面、各機能単位のテストのための仕様書
- 単体試験エビデンス
- 単体試験の結果をまとめたもの
- 結合試験仕様書
- システム全体のテストのための仕様書
- 結合試験エビデンス
- 結合試験の行った結果をまとめたもの
詳細設計書をもとにコードを書いたり、単体試験仕様書を考えるので、ないと困る代物である。
不要といわれる理由
Excel方眼紙を使った詳細設計書のメンテナンスを経験するといらない、と言いたくもなる。
ただでさえ、セルの結合と解除でぐずぐずになりやすいのに
- 手動で版管理する
- 共同編集ができない（新しいExcelではできる）
あたりが組み合わさると、編集コストがかさんで気軽に直せなくなる。あるいは、修正するファイルを間違えたりする。
仕様書とコードの乖離が激しくなると、仕様書を見る機会は減り、仕様を考えている人と実装する人が直接やり取りして完結するようになる。
そして、納品物として必要だから書いているそれらしい仕様書、という本質を見失ったドキュメントが誕生する。
そういう背景はあるものの
システムを作る上の共通の言語として、詳細設計書は必要だと思う。
ごりごりのフォーマットに落とし込んだ何かではなくてもいい。詳細設計を考えた時のアウトプットをすることで、自身の理解が深まるし、まとまっていればのちの改修作業で重要な情報になる。
ほかの人の読みやすさを少し意識すれば、自分はこのように考えています、と説明もしやすい。
案
- 詳細設計書
- Excelかスプレッドシート
- 図式を使えるのは表計算系ソフトなので、セル結合は避けるなどルールを作って編集コストを下げられるのでは?
- Markdown対応のWiki
- 簡単な表組ならできるし、表現力は十分にあるように思う
- MkDocsなどのドキュメント生成ツール
- Markdownで書いてさっとアップできる
- Excelかスプレッドシート
- テーブル仕様書
- テーブル定義ファイルから自動生成
- 丁寧にコメント入っているなら定義ファイルを読めば事足りそう
- 関数・API仕様書
- コードから自動生成
- 自動生成前提でコメントが入っているなら、コードを読めば事足りそう
ざっと思いつくのはこんなところ。
改めて調べてみると、様々なやり方、ツールがあるので、コスパよくドキュメントにできるかもしれない。
雑感
今のところはMarkdown対応のWikiにまとめている。Excel方眼紙でないだけでやる気でるのだから面白い。