Mermaidで図を書く時に個人的に気をつけていること

先日、GitHubでもMermaidに対応をしたことが発表されました。

今回は、GitHubや他サービスでMermaidを書く時に個人的に気をつけていることを書いておきます。
ここに書いてあることは、PlantUMLで書いているときにも気をつけているポイントになります。

図の流れは、LR（左から右）にしておく

特に理由がなければ、フローチャートの流れはLRにしておきます。 LRにしておく理由は2つあり、

PRやドキュメントの文章は、ほとんどが左から右への流れなので、フローチャートでの視線の動かし方も同様にする
構造が深くない構造であれば横長の方が収まりが良い

あまり論理的な話ではないですが、こういうポイントでLRにしていることが多いです。

graph LR

User --> LB
LB --> Nginx
Nginx --> Puma

逆にTB（上から下）にする時もあります。

構造が深く横に収まらない、もしくは複雑化する

こういったケースの時は、TBにすることが多いです。

ノードとリレーションの定義は別々にする

メンテすることがないドキュメントではほとんどやらないですが、ノードとリレーションの定義は別々にしておくとメンテが楽になります。

例えば以下のような定義を書いた時に、

graph LR

User --> LB
subgraph AWS
  subgraph VPC
    LB --> EC2
    EC2 --> Aurora
    EC2 --> ElastiCache
  end
end

一見良さそうにみえますが、「UserがRoute 53にアクセスする」、「EC2がS3にアクセスする」を追加してみます。
愚直に追加すると以下のような定義になりますが、その描画結果は意図しないものになります。

graph LR

User --> LB
User --> Route53
subgraph AWS
  subgraph VPC
    LB --> EC2
    EC2 --> Aurora
    EC2 --> ElastiCache
    EC2 --> S3
  end
end

Route 53は、AWS外に定義され、S3もVPC内に定義されてしまっています。意図していない結果なので、Route 53とS3をAWS内に定義されるように変更してみます。

graph LR

User --> LB
subgraph AWS
  User --> Route53
  EC2 --> S3
  subgraph VPC
    LB --> EC2
    EC2 --> Aurora
    EC2 --> ElastiCache
  end
end

さて、意図した結果になっているでしょうか？
今度はUserが、AWS内に移動してしまっていますね。
さてどうやって修正しますか？
私はこの方式の定義だと、どうやって意図した差分になるのかは思いつかないです。

リレーション定義のみだけで書くと、こういったちょっと意図しない・誤解を与えるような図になってしまうことがあります。
こういう問題が起きないようにするために、ノードとリレーションの定義を分割して定義してみます。

graph LR

%% nodes
User
subgraph AWS
  Route53
  S3
  subgraph VPC
    LB
    EC2
    Aurora
    ElastiCache
  end
end

%% relations
User --> LB
User --> Route53
LB --> EC2
EC2 --> Aurora
EC2 --> ElastiCache
EC2 --> S3

冗長な定義に見えますが、ノードとリレーションを分割して定義することで意図しない描画結果になりづらくなりそうというのが分かるかと思います。
こういった理由でメンテをするようなドキュメントに書く場合は、ノードとリレーションを別として定義しておくと良いです。

さいごに

PlantUMLを昔から書いていたので、その時に気をつけていることを簡単にまとめてみました。
シーケンス図であれば、シーケンス図の気をつけていることがあったり、「強調したい部分は強調して、それ以外には装飾しない」といった点もありますが、今回は省いて最低限気をつけていることを書きました。
図の方が理解しやすいことも多いと思うので、うまくMermaidと付き合って開発していけると良いですね。