TL;DR
SIer業界では、設計書はほぼExcelで作成する文化がある。
そこでこの常識を疑って他のファイル・ツールを提案することで、Git管理・差分の可視化ができ、現場も顧客も使いやすそうなものを調査した。
今回提案するのは、「MarkDown」「plantUML」「Swagger」「draw.io」の４つ。詳しい方にはどれも名の知れたものかもしれないが、そこはご容赦いただきたい。
1. Excel 設計書のメリット・デメリット
① メリット
- 直感的に記載が可能
- ほぼ誰でも Excel を使えるため、学習コストがない
- 表形式での表現が楽
- 機能が多い（カラーの使用・セル結合・連番振りなど）
- 顧客も Office を使用していることが多いため、顧客への可視性は ◎
② デメリット
-
変更管理がほぼできない
- バイナリーデータのため、変更した際、どこに変更が発生したか追うのが難しい
- 意図しない変更を見逃す可能性がある
- 同時に複数人がファイルのどこかを修正した場合、Git による自動マージができない
- 機能が多く、フリーフォーマットがゆえに、記載方法がばらばらになりがち
2. システム開発における主な業務APの設計書とそのフォーマット
| No. | 工程 | 領域 | 設計書 | フォーマット（例） |
|---|---|---|---|---|
| 1 | 基本設計 | 共通 | 業務フロー | Excel（オブジェクトで表現） |
| 2 | IF 仕様書 | Excel（表形式で表現） | ||
| 3 | フロント | 画面遷移図 | Excel（オブジェクトで表現） | |
| 4 | メッセージ一覧 | Excel（表形式で表現） | ||
| 5 | 画面レイアウト | Excel（オブジェクトや画面キャプチャを貼付） | ||
| 6 | 画面項目一覧・画面状態 | Excel（表形式で表現） | ||
| 7 | バック | 機能一覧 | Excel（表形式で表現） | |
| 8 | メッセージ一覧 | Excel（表形式で表現） | ||
| 9 | 詳細設計 | 共通 | 状態遷移図 | Excel（オブジェクトで表現） |
| 10 | フロント | ストア設計 | Excel（表形式で表現） | |
| 11 | 画面状態 | Excel（表形式で表現） | ||
| 12 | バック | 処理設計書 | Excel（表形式で表現） | |
| 13 | 処理フロー設計書 | Visio（オブジェクトで表現） | ||
| 14 | ER 図 | ER 図作成ツール | ||
| 15 | マスタデータ定義書 | Excel（表形式で表現） |
3.Excel の代替ファイル・ツール
3-1. MarkDown
- プレーンテキストで記述が可能。そのため Git での自動マージに対応できる。
- Excel ほど多機能でないが、テーブル作成や段落表示・リストなど最低限の構造体が作成でき、VSCode や GitHub などでプレビュー表示が可能
-
テキスト量や列数が多くなく、かつ高頻度で修正される設計書に最適と思われる
- 例）メッセージ一覧、マスタデータ定義書など
-
GitHub では、プレビューによる差分確認がわかりやすい。
-
[参考]実際の差分確認はここから
3-2. plantUML
- UML の図をプレーンテキストで表現可能
- 独自の文法で記載する必要はあるが、サンプルコードは HP にもあり、文法は比較的簡単。
- 初めて以下の業務フローを作成したが 15 分程度で作成できた。サンプルコードはこちら
- プレビュー表示・画像出力には Java のインストールは必要。
- 業務フローや機能設計書のフロー図などの設計書に有効。
- [参考]plantUMLのホームページ
3-3. Swagger
-
YAML または JSON ファイルで API の IF の仕様を定義することで、Web 画面からプレビューでリクエスト・レスポンスがわかりやすく表記される
-
プレーンテキストのため、Git での変更管理は容易
-
外部 IF 仕様書から様々な言語・FW でモックサーバのコードを自動で生成してくれるため、画面イメージを最速で作ることができる。（レスポンスデータは自身で作成する必要があるが、1APIに対して複数のデータパターンはできなそう）
-
対応 FW の中には、フロントの UT で使用している Node.js の express のほか、Java の spring など多岐にわたる。
3-4. Draw.io
- オブジェクトを活用した図形を作成するツール
- メインは Web ツールだったが、VSCode の拡張機能で VSCode でも編集が可能
- .drawio.svg ファイルを活用することで、ファイルのエクスポートをすることなく、VSCode での編集および GitHub での差分確認を１ファイルで完結できる
- GitHub での差分確認は、テキストほど明確ではないものの、スクロールバーを使用した差分確認など直感的に確認できるものが多い
- [参考]記事：draw.ioをgithubで差分確認する
- 脱 Excel 化する対象は、現状オブジェクトで表現している設計書だが、Excel に比べて、劇的に変化するわけではない。詳細設計書など、顧客へ納品しない設計書からサンプル的にトライしてみるのはありか
最後に
今回は既存の設計書を別の方法でどう表現するかという観点で記載したが、そもそも各設計書の作成意図を考えることで、無駄な設計書を省いて実装を正とする考え方も重要だと思うため、今後はそういった観点でなんらかの記事が書けたらと思う。
本内容は、以下のGitHubでも公開しています。
https://github.com/Hiroyuki1995/Escape-from-Excel