会社でフロー図を書こうと思って PlantUML と mermaid.js を比べてみる


ずっと PlantUML でクラス図を書いてきたけど、書きたいフロー図が PlantUML で書けなかったので mermaid.js を触ってみた。
会社に導入するって観点で比べてみる。

PlantUML は結構な量書いたので慣れているけど mermaid.js は数日触ってみた程度なので、理解度が違うのは勘弁で。

## 概要
サイト紹介とサンプル紹介

### PlantUML
[公式サイト](http://plantuml.com/)

`.puml`というファイルを書いて描画させるとこんな図になる

クラス図
![class.jpg](https://qiita-image-store.s3.amazonaws.com/0/113398/2e1a1668-4d54-bef8-84bd-3f8ff662c461.jpeg)

シーケンス図
![sequence.jpg](https://qiita-image-store.s3.amazonaws.com/0/113398/e001282c-deaa-abe2-bb60-06edbbb94ee8.jpeg)

アクティビティ図
![activity.jpg](https://qiita-image-store.s3.amazonaws.com/0/113398/c96427d7-f784-c7e8-a8e6-87e373faeb17.jpeg)


他にもステートマシン図とかユースケース図とかも書ける

### mermaid.js
[公式サイト](https://mermaidjs.github.io/)

`.html`ファイルを書いて描画させるとこんな図になる

クラス図
<img width="537" alt="class.png" src="https://qiita-image-store.s3.amazonaws.com/0/113398/81b5c516-76bd-e8a9-b8ca-378df7496b05.png">

フローチャート
<img width="537" alt="simple.png" src="https://qiita-image-store.s3.amazonaws.com/0/113398/cecc1f23-5f32-5fed-c005-ab465f806cf6.png">

他にもガントチャートとかも書ける

## 出来ること
実用する際に融通が利きそうなこと、ネックになりそうなこと

### PlantUML
+ :ok: 提供されている図はどれも結構凝ったことが出来る印象
  + 矢印にテキストを書いたり、クラス図中のテキストの字の色を変えたりも可能
+ :ok: 別の`.puml`ファイルを読み込めるのでファイル分割が可能
+ :ng: 特定の記述があるとＸＸ図のコードだと判断され描画されるので、１枚に複数種類の図を併記することは出来ない

### mermaid.js
+ :ok: `.html`なので図の部分以外の箇所の融通がすごい利く
+ :ok: フロー図では`click`が設定できた
  + 図のパーツそれぞれにマウスオーバー時のテキスト表示、リンク化、`onclick`が設定できる
+ :ng: クラス図はあんまり得意じゃあないって感じがした
  + 見た目の整形もあまりできなそうだし、`click`も出来なかった
+ :question: ファイル分割は出来ない
  + `.html`なのでどうにでもなるけど

## 試しやすさ
初めて触ってみる際の準備や手間について

### PlantUML
+ 使ったことないけど、[オンラインエディタ](http://www.plantuml.com/plantuml)がある
+ ローカルに準備をしようと思うと`.jar`と`Graphviz`が必要になるし、プレビューも少し面倒

### mermaid.js
+ こちらも使ったことはないけど、やっぱり[オンラインエディタ](https://mermaidjs.github.io/mermaid-live-editor/)がある
+ ローカルだと CDN で mermaid.js を読んでブラウザで見る方法があり、PlantUML に比べると相当楽

最低限これだけを書いて`simple.html`としてブラウザで開けば良い。（chrome でのみ確認）

```html:simple.html
<div class="mermaid">
graph LR
    A --> C
    B --> C
    B --> D
    C --> D
</div>

<script src="https://unpkg.com/mermaid/dist/mermaid.min.js"></script>
```

## エディタとローカルプレビュー
自分が書いたり確認したりする時のこと

### PlantUML
+ [IntelliJ IDEA](https://www.jetbrains.com/idea/) に [PlantUML integration](https://plugins.jetbrains.com/plugin/7017-plantuml-integration) というプラグインがあり、それでプレビューも出来る
+ 新規作成で図の種別が選べて、出来たファイルに最初からサンプルが書いてあるので、割とある程度の物は適当に書ける

<img width="249" alt="new.png" src="https://qiita-image-store.s3.amazonaws.com/0/113398/24563e7d-513e-81db-144f-2e6967ba107d.png">

+ 他にもエディタは色々あるけど、僕はこれ以外紹介できない

### mermaid.js
+ IntelliJ IDEA にプラグインはなさそうだった
+ [Haroopad](http://pad.haroopress.com/) ってエディタが設定が不要でプレビューも出来るらしい
+ けど結局は`.html`とブラウザで良いので僕は vim で書いている

## オンラインプレビュー
テキストベースだから git で管理したいしレビューもちゃんとやりたいので、GitHub のソースコードを楽にプレビューできないといけない

### PlantUML
+ chrome 拡張に [PlantUML Viewer](https://chrome.google.com/webstore/detail/plantuml-viewer/legbfeljfbjgfifnkmpoajgpgejojooj?hl=ja) というのがある
+ そういえば前に紹介記事を書いた
  + [GitHubで差分を見る時にPlantUMLを描画させる](https://qiita.com/suzuki-hoge/items/648f5dbeeec5365666eb)

### mermaid.js
+ パッと探した限りだと、GitHub 上に表示された`.html`コードをプレビューする chrome 拡張とかは見つからなかった
  + ありそうだけどな？
+ github pages があるけど、あれは master ブランチにあるものしか閲覧できないので、マージ前のレビューとしては使えない

## セキュリティ
会社のシステムやプロセスについて記述する際の注意

### PlantUML
+ chrome 拡張で描画をするのは外部にソースを送って画像を送り直して貰う構成のはずなので、企業秘密を含んでいるソースで利用するのは不適切
+ オンラインエディタも同様

### mermaid.js
+ こちらのオンラインエディタもおそらく同様
+ github pages は private repository であっても閲覧制限がかかっているわけではないのでこれも厳密に考えると利用するべきではない

## ドキュメント閲覧
書き上がったドキュメントを周知する

### PlantUML
+ セキュリティの問題も考えると、ローカルで画像として保存したものを社内のポータルや社内チャットで共有するという形になりがち
+ それかソースの改版の際に都度ローカルで画像を作り、それを一緒にコミットし、閲覧は GitHub の private repository で行う
+ 周知相手が同じコンポーネントのエンジニアだけなら、git でローカルのソースを更新して各々エディタで確認するという方法もある
  + クラス図等であればソースと一緒に自然と更新されるしエディタで開くのも妥当
  + が、プロセスを定めた図やチートシート等のプロダクトコードと関係ない図だと微妙

### mermaid.js
+ gitlab pages というのがあるらしい
  + 社内に gitlab が立ってるので試そうと思ったんだけど、どうも github pages と比べて格段にめんどくさそう
+ `.html`でしかないので、適当な検証用 web サーバを間借りして置いちゃうことが出来るかも知れない

## まとめ
mermaid.js はちょっとだけとは言え、両方を触ってみたので総括してみる

### PlantUML
+ クラス図は圧倒的にこちらが得意
+ `include`が使えるのでファイル分割もこちらが得意
+ 少し導入や閲覧で下げちゃったけど、プロダクトコードと一緒に管理するクラス図やシーケンス図ならとても良いと思っている

### mermaid.js
+ `.html`という点を活かすと出来上がる資料の融通はかなり利きそう
+ マウスオーバーで補足説明を添えたり、別資料へのリンクが出来るのはかなり良さそう
+ 冒頭で述べた書きたいフロー図は思った以上にイイカンジで実現できそうなので、もう少し馴染んだらまた紹介したい

触ってみた感じだと案外得意不得意がはっきりしているので、必ずしもどちらかだけに決めることもないかな、というのが今の印象。