ITエンジニアとして仕事をしていると、システム設計などドキュメントを作成する場面は多くあります。このようなドキュメントの作成に役立つツールが多く開発されていますが、そのトレンドと合わせて特徴を紹介します。
ドキュメント作成ツールに求めるもの
設計書などのドキュメントを作成するとき、すぐに思いつくのはWordなどの文書作成ソフトを使うことです。画像を挿入するときは、PowerPointなどで作図してスクリーンショットを取得し、貼り付ける方法もあります。
多くの会社では、WordやExcel、PowerPointなどのソフトウェアが導入されていることが多く、手軽に使えます。どのパソコンでも開けることから、ファイルの共有という観点でも便利です。
また、Microsoft社の「Visio」のような、作図ソフトウェアを使うこともあります。専用のソフトウェアを導入する必要はありますが、システム設計などに役立つアイコンなどが豊富に用意されており、初心者でも使いやすいことが特徴です。その他にも、社内で何らかのソフトウェアを標準として定めていることもあるでしょう。
■ドキュメントもバージョン管理したい
このような専用ツールは便利な一方で、ITエンジニアとしてプログラミングなどの仕事をしていると、ドキュメントもバージョン管理をしたいものです。専用のソフトウェアでしか開けないバイナリ形式＊のファイルでは、差分を抽出することが難しく、どこを変更したのかを把握するのが大変です。
このため、設計書を作成するときにテキストファイルとして保存する方法が考えられます。ソースコードにコメントとして埋め込んで記述する「JavaDoc」や「Doxygen」のようなツールもありますし、Markdown形式などで作成する方法もあります。
いずれもテキストファイルとして保存し、Gitなどでバージョン管理をすることを目的としています。図もPowerPointなどの専用ソフトウェアを開いて画像で保存するのではなく、テキスト形式で作図することを考えるのです。文章や画像をテキストで管理できれば、変更点を把握しやすくなります。
＊テキスト形式以外の記述形式。2進数で表現するため人間が見ても理解することは難しいが、プログラムでは効率よく処理できる。
Webブラウザだけでも使える便利なツール
テキスト形式で作図するといっても、具体的な動作がわからないという人もいるでしょう。こんなときに便利なのが、Webブラウザだけで動作を確認できるツールです。よく使われるものとして、「Mermaid」や「Excalidraw」、「diagrams.net（旧draw.io）」、「PlantUML」などがあります。ここではそれぞれの特徴を見てみましょう。
Mermaidはフローチャートやクラス図などシステム開発に必要な図だけでなく、円グラフやガントチャートなどビジネスでも使える図を手軽に作成できます。
Webブラウザだけで実行できる「Live Editor」という機能を用意しており、図のように画面左側にテキスト形式で入力した指示が、右側に図として表示されます。
Excalidrawは四角や丸、矢印といった基本的な図形を組み合わせて自由な図を作成できることが特徴です。また、フリーハンドで描くこともできるため手書き風の図を作成できますし、任意の位置に画像を挿入できます。
このファイルは「.excalidraw」という拡張子で保存されますが、その実態はJSONファイル＊です。このため、テキストエディタで編集できますし、バージョン管理ソフトで差分を抽出することもできます。
＊JavaScriptのオブジェクトをテキスト形式で表現するために作られた表記法。人間にもプログラムにも理解しやすい。
diagrams.net（旧draw.io）は、Visioに似た操作性を持つソフトウェアで、フローチャートやER図＊、UML＊などシステム設計に必要な要素を備えています。
＊データベースのテーブル間の関係などを表現するときに一般的に使われる図。
＊システム開発における設計段階で使われる一般的な図の表記法。
このファイルは「.drawio」という拡張子で保存されますが、その実態はXMLファイルです。これもテキストエディタで編集できますし、バージョン管理ソフトで差分を抽出できます。
PlantUMLはUMLのほか、ネットワーク図やガントチャート、マインドマップなど幅広い描画ができるソフトウェアです。「Online Server」という機能があり、これもWebブラウザだけで動作を確認できます。
VS Codeなどローカル環境でも使えるように
Webブラウザで使うのではなく、手元の環境で使いたいことも多いでしょう。作成したデータがクラウド上に保存されことに不安がある、インターネットの速度によって動作が不安定になる、などの理由が挙げられます。
このようなときは手元の環境にインストールして、テキストエディタなどで作成する方法が便利です。テキストエディタの代わりに、Windowsに標準で付属するメモ帳などのソフトウェアを使うこともできますが、「Visual Studio Code（VS Code）」などのテキストエディタを使うと効率よく作成できます。また、VS Codeでは作成した図をプラグインによって手軽に確認できます。
上記で紹介したMermaid、Excalidraw、diagrams.net（旧draw.io）、PlantUMLのいずれも、VS Codeのプラグインが提供されており、手元に保存したファイルをVS Codeで編集できます。
Mermaidで作成した図は、次のように「```mermaid」で始まるブロックに書くことでMarkdown形式の文書に埋め込んで使えることも多いものです。つまり、作成した図を画像として出力するのではなく、テキスト形式のまま埋め込んで使えます。
# Markdown文書の例
次のように書くと図を埋め込める。
```mermaid
flowchart TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
C -->|One| D[Laptop]
C -->|Two| E[iPhone]
C -->|Three| F[fa:fa-car Car]
```
Mermaid以外のツールでも、手元で使うにはいずれもプラグインのインストールが必要です。PlantUMLを動作させる場合にはJavaが必要で、Graphvizというツールを別途インストールする必要もあります。
このように、導入に少し手間はかかりますが、手元の環境で使うと高速に動作しますし、テキスト形式で管理できることが特徴です。
まとめ
今回はITエンジニアがドキュメントを作成するときに便利な、テキスト形式で図を作成できるツールについて紹介しました。PowerPointやVisioなどで作成した図のバージョン管理に悩んでいる人は、ぜひ試してみてください。
増井技術士事務所代表。技術士（情報工学部門）。情報処理技術者試験にも多数合格。ビジネス数学検定1級。「ビジネス」×「数学」×「IT」を組み合わせ、コンピュータを「正しく」「効率よく」使うためのスキルアップ支援や、各種ソフトウェアの開発、データ分析などを行う。著書に『Pythonではじめるアルゴリズム入門』『図解まるわかり プログラミングのしくみ』『「技術書」の読書術 達人が教える選び方・読み方・情報発信&共有のコツとテクニック』、最新刊の『実務で役立つ バックアップの教科書』（翔泳社）がある。
※本記事に記載されている会社名、製品名はそれぞれ各社の商標および登録商標です。
※本稿に記載されている情報は2025年1月時点のものです。
