📃

開発現場で使える！VS Codeのdraw.io拡張で実現する設計ドキュメントの効率化術

Mutsumix

2025/04/02に公開

 この記事のターゲットシステム設計フェーズでお客様との要件を聞き出した後に作成する、図表を含むドキュメントの作成や管理の効率化に悩む方々に向けた内容です。

 ドキュメント作成あるある：図と説明文の分離問題システム開発プロジェクトでは、要件定義や設計フェーズにおいて、お客様との認識合わせが非常に重要です。特に、システムの概要やフローを図とともに説明し、レビューしてもらうケースが多くあります。
開発現場でのドキュメント作成あるある早く言いたい♪

文書と図の分離管理めんどくさいがち：それぞれ別のツールで作成し、最終的に統合する作業が発生

修正手間かかりがち：文書や図に修正が入るたびに再統合が必要でデグレもありがち

レイアウト難しいがち：図と説明文が離れてしまうと読みづらいので改ページの位置気にしがち

バージョン管理できないがち：最新版がどこかわからない

 draw.ioとMarkdownの組み合わせによるソリューションVS Codeのdraw.io拡張機能とMarkdownを組み合わせることで、これらの課題を効率的に解決できます！



文章と図の更新をリアルタイムにプレビューできます

 ポイント1. VS Codeとdraw.io拡張の導入VS CodeはテキストエディタでありながらMarkdownのプレビュー機能も充実しており、draw.io拡張を追加することで、図の作成が同一環境で行えるようになります。

ツールの切り替えによるスイッチングコストバカにならないので、地味に便利です。



拡張はdraw.ioで検索すると出てきます

 ポイント2. Markdownでドキュメント作成Zennで記事を書いている方には説明不要ですが、Markdownは軽量なマークアップ言語で、シンプルな記法ながら文章に簡単に構造を持たせられるなど、幅広い表現力を持っています。

開発者にとっては割と当たり前な記法ですが、NotionやSlackといったツールでもその記法が使えることから、非エンジニアにも広がっていくと思っています。

さらに、バージョン管理ツールとの相性がよく、変更点の管理が容易といったメリットがあります。

 ポイント3. draw.io拡張の活用お絵描きツールにはastahや、最近ではMiroといったものがあります。

Excelやパワーポイントを使っている現場も多いでしょう。

draw.ioは無料なので導入がしやすいのがポイントです。

そしてdraw.io（のVS Code拡張）には、以下のような優れた特徴があります

.drawio.pngや.drawio.svg形式で保存することで、画像としても編集可能ファイルとしても扱える
Markdownファイル内で画像として参照できる
リアルタイムでプレビューが可能
生成AIとの相性が良く、概要説明から叩き台となる図をXML形式で出力してもらえる


拡張機能インストール後は、.drawio.pngといった拡張子のファイルを作成すると、編集画面が表示されます

 ポイント4. GitHubとの連携作成したドキュメントはGitHubのプライベートリポジトリで管理することで、以下のメリットが得られます：
バージョン管理が容易 ←これめっちゃ重要！他のドキュメントツールにはないメリット
お客様をリポジトリに招待してレビューしてもらうことが可能
PRレビューなどのGitHubの機能を活用したコラボレーション
セキュアな共有環境の実現

 実際にやる場合の手順
 Step 1: プロジェクト開始時の環境準備VS Codeにdraw.io拡張をインストール
GitHubにプライベートリポジトリを作成
お客様にリポジトリへのアクセス権を付与（可能な場合）

 Step 2: ドキュメント作成プロセスMarkdownファイルで文書のベースを作成
draw.io拡張で必要な図を作成（.drawio.png形式で保存）
Markdown内で図を参照
VS Codeのプレビュー機能で全体の見栄えを確認



 Step 3: お客様とのレビュープロセス（できたらいいね）変更をGitHubリポジトリにプッシュ
お客様にレビューを依頼（GitHubのIssueやPR機能を活用）
フィードバックに基づいて修正
修正版を再度プッシュしてレビュー

 お客様とのコラボレーション方法
 GitHub Organization活用のメリットお客様をGitHubのOrganizationに招待することで、PRレビューなどを通じたフィードバックが直接可能になります。これには以下のメリットがあります：
コミュニケーション機会の増加
開発チームとお客様の一体感醸成
サービス利用に関するリテラシー向上
継続的な開発のための基盤構築

 課題と対応策ただ、そうはいってもお客様によってはGitHubの操作に慣れていない場合や、IT管理方針で社外アカウント利用が制限されているケースもあります。

そのような場合は、作成したMarkdownをGoogleドライブといったツールで共有する、PDFに書き出してみてもらう、といった方法でレビューしてもらう必要があるでしょう。

 まとめVS Codeのdraw.io拡張とMarkdownを組み合わせることで、設計ドキュメント作成の悩みを大きく解消できます。文書と図表を一つの環境で作成・編集できるため作業効率が向上し、修正も独立して簡単に行えます。改ページの概念がないため、常に図と説明文が適切に配置された読みやすいドキュメントが完成します。
さらに、GitHubでの管理により変更履歴が明確になり、お客様との共同レビューもスムーズに進められるようになります。この手法は単なるドキュメント作成の効率化だけでなく、開発フェーズ全体でのコラボレーション促進にもつながるでしょう。
弊社ではこのやり方がもっと広まって欲しい、という思いと実際の開発効率の良さから一部でこの方法を使ったドキュメント作成を行っています。

皆さんも開発現場でのドキュメント作成・管理に悩んだら、この方法を参考にしてみてください！