2022/10/31 New!!
この記事の続編となるGitlab Wiki整備編を公開しました。

概要

現在社内で作られるドキュメントのほとんどがExcelで作成されています。

議事録
提案書
見積
設計書
テスト仕様書
打ち合わせで使う資料
etc...

この中の一つである設計書を脱Excel化しようと試みたのでその過程と結果を何回かに分けて
Qiitaにアウトプットしようと思います。

前提条件

プロダクトバックログ及びスプリントバックログはBacklogにて管理する
ソースはGitにて管理し、GitLabを利用する

取り組む内容

①Excelに変わる新たな設計書作成手段の導入

今までExcelでしかやってこなかったのでまずは調べる所から

②設計書のテンプレート作成

テンプレートを用意しておかないと人によってこの項目を書いた/書いてないが分かれてしまいそう。
そのため各資料ごとに簡単なテンプレートを作成しておく。

③Excelから新手段への乗り換え方法の検討

いきなり新方式を強いるのも労力がかかりそうなので徐々に慣れてもらうにはどのような
進め方をしていくのがベストか検討する。

④作成/編集する際の最低限のルール策定

差分でチェックするという目的がある以上無暗に更新されても困るので
あらかじめルールを決めておく（ルールが浸透するか分からないのでかっちり作りすぎない）

選定候補

①設計書作成用ツールの導入

例：Cacoo、astah（弊社ではCacooを利用中）
※参考URL

設計書作成に特化しているため細かい所まで気が利いている。
商用利用だと月額費用が発生してしまうがツールを絞ればある程度抑えられる。
仮にサービスが終了した場合編集できなくなってしまうのでは？という不安はある。

②すでに利用しているシステムのWiki機能の活用

例：GitLab、Backlog(今回の自社プロジェクトで使用しているツールです）
マークダウンでゴリゴリ作っていく。特徴は文ベースで処理の中身や説明を書いて行き、後々変更があった時に
差分が確認しやすくなる。（Excelだとファイルが増えていったり「●●●●年●●月●●日変更」と書くはめになる）
後、Wikiとしての機能が既に用意されているのでページを追加していくだけで資料体系が出来上がっていくし
見出しをちゃんとつければアウトラインが分かりやすい。
図の作成はplantUMLなどの外部コンポーネントを使えば作成できるものもあるが、融通が利きづらい部分もある。

③マークダウンをHTML形式に変換するホスティングサービスの利用

例：Honkit（他にもありそう）
Wikiと同じくマークダウンで作っていく。ホスティングサービスを立ち上げるメリットとしては
他２つに比べて有志が開発するプラグインの幅が広いというのと、好きな環境に立ち上げやすいという点。

結論

図を作成する場合はCacoo、仕様等を文や表で表す場合はGitLabのプロジェクトのWikiを使用することにしました。

Cacooを選定した理由＋作成する対象資料

Excelの図形だと表しきれない設計図独特の図形もCacooだと用意されているというのと
複数人で同時に編集が出来るというのが大きいです。後、共有する際もリンクを送ればいいので楽

対象資料

ハードウェア構成図
ソフトウェア構成図
ネットワーク構成図
システム連携図
画面遷移図（Mermaidをマークダウンに埋め込む手もあり）
処理フロー（Mermaidをマークダウンに埋め込む手もあり）
ER図

GitLabのWikiを選定した理由＋作成する対象資料

マークダウンで設計書を作るという部分に対する選択肢は
1.BacklogのWiki機能
2.GitLabのWiki機能
3.Honkit
の3つでしたが、ソースコードを管理する場所とドキュメントを管理する場所を統一したいという思いから
GitLabのWiki機能を選びました。
BacklogのWikiはどちらかというと１システムより１プロジェクトに対するWikiなので
設計書というシステムに紐づくものはGitLabの方がいいのではという社内の意見が参考になりました。

対象資料

画面一覧
画面入出力項目一覧
画面ごとの処理の流れ
帳票一覧
帳票入出力項目一覧
帳票出力使用
バッチ処理一覧
バッチ処理の流れ
DBテーブル一覧
DBテーブル定義
API一覧
API仕様書（インターフェース、処理内容）
非機能要件定義

まずはブラウザ上でWikiページを作成して、慣れてきたら
VSCodeを使用して編集＋Git連携してコミット&プッシュでもいいかも

Excelについて

今まで「脱Excel」と繰り返していましたが、イメージだけをパパっと伝える一時的な資料など
その場限りの資料という前提で、相手側に見てもらうための準備の手間が多いと感じた場合は
Excelでもいいと思います。
後、ちゃんと表計算ソフトとして意味のある資料はもちろんExcelでいいと思います。

2023/07/14追記

Wiki以外で代替可能なドキュメントがいくつかあるのでそちらも共有します。

ER図

ER図を書くことに特化したツールがあるため、Cacooではなく専用のツールを選択するのも有りです。

API設計書

SwaggerなどのOpenAPI形式の定義ファイルを扱えるツールがあります。
このツールが設計書、モック、自動テストを全て兼ねることが出来るそうです。
このツールを使う時にWikiにも仕様を書いてしまうと二重管理になってしまうのでWikiに記載しないという判断もあります。

画面遷移図

FigmaやAdobe XD等のツールで画面のワイヤーフレームを作る際に、画面遷移図も合わせて作ってしまうこともあります。