ドキュメント
設計書

自分なりのシステム設計時の考え方

More than 3 years have passed since last update.

最初にお断りしておきますが、テクニカルな話ではありません。自分はこう考えてるな、というメモ的な内容です。


  1. 大まかなユースケース図で全体像を書く。

    ユースケース上では、誰かが情報を登録し、誰かが照会し、どこぞかのシステムに外部連携する、といった情報を盛り込む。できれば、大まかにユースケース上でスコープに含まれるもの、含まれないものが表現されると嬉しい。規模の大きなシステムの場合は、スコープは別のドキュメントに定義を書く。


  2. ユースケース図では、時間軸に沿って情報が流れている様子が表現できないので、ユースケース図と同じ粒度で業務フローを書く。書き方は1つに定まってないけど、多くの場合はアクティビティ図を使っています。


  3. アクティビティ図から、代表的なユースケースに絞って、画面フローを書く。場合によっては、画面設計も書いてしまう。画面設計といってもワイヤーフレーム的に表示要素の配置を考えるのではなくて、入力項目やボタンを並べるだけのもの。


  4. 画面フローの中で、サーバー側の処理が読み取れないというか、画面フローだけでは開発できない部分に絞って、フローチャートかシーケンス図で補う。


  5. この段階で、ER図とシーケンス図と画面設計を行ったり来たりして、整合性を高める。ER図頭で画面設計を眺めることで、画面とデータ構造の整合性の誤りを正すことができるし、画面設計頭でER図を眺めると、正規化しすぎて処理速度が考慮されてないとか、ER図の細かなチューニングができる。


  6. 場合によっては、APIの洗い出しをして、シーケンス図、画面設計、ER図の間を行ったり来たりして整合性を高める。


  7. 出揃ったところで、データベース設計書やら、APIのI/O定義書を清書して、物理名を決める。


  8. このときもまた、DB的な物理名とAPI名を行ったり来たりして命名の整合性を高める。


一番大事にしていることは、ドキュメントというのは思考のツールでありコミュニケーションのツールであるということ。

思考ツールとして有効活用できるように、ダイアグラムを書く工程で、検討課題を抽出して、ディスカッションのアジェンダをチームに投げて意思決定したり、ダイアグラムとダイアグラムを突き合わせて整合性のチェックをしたり、したい。

読むのが誰かということを想定して、書いた文書は全て、読み手の目線で読みなおして、文書構成や言葉の訂正を入れることを怠らないようにしたい。