入社して4日目にVSCode の draw.io プラグインでシステム構成図を作成したら褒められた話
はじめに
システム構成図はプロジェクトの全体像を理解するために欠かせないツールです。
しかし、メディカルフォースにはシステム構成図がありませんでした。
そんな中、入社して4日目に VSCode の draw.io プラグインを導入し、作成および管理方法までまとめたところ、大変好評でしたので、その詳細を共有します。
やったこと
- draw.io プラグインの導入
- VSCode の推奨プラグインファイルを作成
- 運用方法の md ファイルを追加
.
├── .vscode
│ └── extensions.json
├── images
│ ├── README.md
│ ├── system-diagram.drawio
│ └── system-diagram.png
├── README.md
├── package-lock.json
├── package.json
└── src
1. draw.io プラグインの導入
インストール
Visual Studio Code に「Draw.io Integration」を導入
作成
インストール後、エクスプローラーからファイルを作成し、system-diagram.drawioのように.drawioファイル作成します。
ダブルクリックするだけで、Visual Studio Code 内で直接編集することができます。
編集が完了したら、ファイルを保存し、必要に応じて PNG 形式でエクスポートしてください。
2. VSCode の推奨プラグインファイルを作成
以下のように作成します。
.vscode/extensions.json
{
"recommendations": [
"hediet.vscode-drawio"
]
}
3. 運用方法の md ファイルを追加
システム構成図の管理を効率化するために、運用方法.mdを作成しました。
運用方法.md の内容
運用方法.md
# 構成図など
このディレクトリには、メディカルフォースAPIのシステム構成図やその他画像が含まれています。
## ディレクトリに置くべきもの説明
```
images
├── README.md
├── system-diagram.drawio
├── system-diagram.png
├── ${filename}.drawio
└── ${filename}.png
```
- `${filename}.drawio`: システム構成図の編集可能なソースファイルです。\
このファイルは[hediet.vscode-drawio](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio)で編集可能です。\
または[Diagrams.net](https://app.diagrams.net/)で開くことができます。
- `${filename}.png`: システム構成図のPNG形式の画像です。drawioファイルを編集後、エクスポートしてください。GitHub上で直接閲覧することができます。
## 構成図の閲覧
システム構成図を閲覧するには、以下の画像をクリックしてください。
※ README.mdには以下のように相対パスで記載すると画像が読み込めます。
```
```
## 貢献
この構成図に変更を加えたい場合は、`.drawio`ファイルを[hediet.vscode-drawio](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio)のプラグインを用いて編集してください。\
変更後の画像を`system-diagram.png`にエクスポートしてください。
### 拡張機能のインストール方法
プラグインをリコメンドしてくれるよう、`.vscode/extensions.json`に記載しています。\
手動でインストールする場合、以下の手順にしたがってください。
1. Visual Studio Codeを開きます。
2. 拡張機能ビューを開くために、サイドバーの「拡張機能」アイコンをクリックするか、`Ctrl+Shift+X`（Windows/Linux）または`Cmd+Shift+X`（Mac）を押します。
3. 検索バーに「hediet.vscode-drawio」と入力します。
4. 検索結果から「Draw.io Integration」を見つけ、インストールをクリックします。
インストール後、`.drawio`ファイルをダブルクリックするだけで、Visual Studio Code内で直接編集することができます。編集が完了したら、ファイルを保存し、必要に応じてPNG形式でエクスポートしてください。
まとめ
VSCode の draw.io プラグインを導入することで、システム構成図の作成と管理が大幅に効率化されました。これにより、プロジェクトの透明性が向上し、コミュニケーションがスムーズになりました。また、コードで管理されるため、gitとのシナジーも良かったです。今後もこのツールを活用し、さらに改善を続けていきたいと思います。
Discussion