こんにちは。サーバエンジニアの桐島です。
今回は、図（フローチャート、シーケンス図など）をチームで継続的に管理するための個人的なベストプラクティスを紹介したいと思います。
図の有用性と、継続的な管理の必要性
図って便利ですよね。
以下の様な図があると、チーム内での認識合わせを正確に素早く行うことができます。
- サーバ構成図
- アプリ-サーバ間処理のシーケンス図
- APIプログラムの複雑なロジックのフロー図
- ER図
ただ、プロジェクトのドキュメントに含まれる図がすべてメンテナンスされ、最新の仕様と図がマッチし続けているケースは少ないのではないでしょうか。
図は有用なのですが、管理し続けなければその有用性を失い、いずれ削除される運命にあります。
図の継続的管理への課題
では、図が管理されない原因は何でしょうか。
具体的なケースを幾つか挙げてみます。
- 再編集できないフォーマットで図が作られている
- ホワイトボードに書いた図を撮影した写真を共有する
- 再編集できない画像ファイルとして共有する
- 再編集できるフォーマットで作られているが、閲覧・編集するために特殊なツールが必要となる
- 専用ツールのインストールが必要となる
- インストールに手間が掛かる
- Mac と Windowsでツールの動作が異なる
- ツールの学習コストが高い
- 図の存在が知られていない（図が散在している）
- 知らない間に図の内容が古くなっている
これらケースから考えると、大きな原因は以下の2点にありそうです。
- 図の閲覧、作成、編集がハイコスト（特に編集）
- 図を作成するタイミングが決まっていない
この課題をクリアし、図を継続的に管理するための方法を考えたいと思います。
継続的画像管理のアイデア
先に結論を書くと、以下方法が良いと考えています。
- SVG形式で図を扱う
- draw.io と GitHub で図を作成、編集する
- 図の変更をPullRequestに含める
この方法のメリットは以下となり、上述の課題を解決できそうです。
- チームメンバ全員が簡単に同じ方法で図を閲覧、作成、編集することが可能
- 図の閲覧、作成、編集のローコスト化
- プログラムと図を紐付けてバージョン管理することが可能
- 図の作成、更新タイミングの明確化
次に、具体的な手順を見ていきたいと思います。
具体的手順1（図の作成）
1. draw.ioで作図
draw.io で図を作ります。
2. SVGとしてexport
SVGファイルとして保存することで、draw.ioで再編集可能となります。
export実行します。
3. export先として GitHubを選択
draw.ioとGitHubを連携するためには認証が必要です。
連携したGitHubアカウントがアクセス可能なリポジトリ一覧が表示されます。
4. export先のリポジトリ・ブランチ・ディレクトリを選択
commit メッセージを書き、OKボタンを押すとcommit完了です。
（SVGファイルが指定リポジトリに追加されます）
具体的手順2（図の編集）
1. GitHub上のファイルを開く
作成時と同様の手順でGitHub上のsvgファイルを選択します。
（リポジトリ・ブランチを選択可能です）
2. 変更をcommit
GitHub上のファイルを編集した場合、編集後に「Unsaved changes. Click here ti save.」というボタンが表示されます。
これをクリックすると、commitメッセージを書いてcommitすることができます。
（commit先は、ファイルを開く時に指定したブランチとなります）
具体的手順3（図の差分確認）
PRのレビュー時に画像の差分を確認しますが、GitHubのrich diffツールが素晴らしいです。
SVGファイルの文字列差分では変更箇所は分かりませんが、rich diffツールを使うと画像の変更箇所を素早く把握することができます。
2-up で差分確認した場合
Onion Skin で差分確認した場合。
具体的手順の紹介は以上となります。
ブラウザだけで図の作成、git commit/push、レビューまで完結できていることは驚きですね。
まとめ
図を継続的に管理するための個人的なベストプラクティスを紹介しました。
ただ、図の扱いはチーム（規模、構成、状況等）により、メリットもデメリットも異なると思います。
例えば、リモートワーカーが居るチームでは図を作成し共有することによるメリットが大きいですが、小さなチームの開発初期段階では、作図コストのデメリットが大きいかもしれません。
また、必要となる図の対象・粒度もチームにより異なると思います。
今回の記事が、チームに最適な図の共有方法を考える参考になれば幸いです。