Qiita での UML 記述

Qiita で PlantUML および mermaid が使用できるようになったということで軽く比較したいと思います。
それぞれの正式な書式については公式サイトをご確認ください。

cf. PlantUML
cf. mermaid

Pros/Cons

先に PlantUML と mermaid について個人的な見解を述べさせていただきます。

PlantUML シーケンス図

Pros

図表が画像で表示される
描画パーツを細かく指定できる

Cons

対応しているサービス以外、ローカルのエディタ（VS code など）で図表化するためには Java の設定が必要となる
ちょっと図表が古めかしい

mermaid シーケンス図

Pros

図表の文字がテキストとして認識できるためコピペがしやすい
ローカルのエディタで拡張機能を設定するだけで図表化される
PlantUML よりモダンな図表
GitHub で採用されている！

Cons

図表を画像化するのに一手間かかる

全体的な書きやすさなどは慣れの部分が大きく、極端に有利不利があるようには思えません。
ただ、やはり GitHub に採用されたという点が今後いちばん界隈に影響しそうなので、PlantUML の資産がなく、新規に始めるのであれば mermaid の方が無難な気がします。

PlantUML.1

```plantumlで開始するだけで、@startuml および @enduml は不要となっています。

終了も```で閉じるだけとなります。

```plantuml
Alice -> Bob: Authentication RequestBob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
```

本文中に上記コードを記述すると以下のように表示されます。

mermaid.1

こちらも同様に```mermaidで開始しますが１行目に図表の種別を記述する必要があります。シーケンス図の場合は sequenceDiagram となります。

終了は```で閉じるだけとなります。

```mermaid
sequenceDiagram
    Alice->>Bob: Hello Bob, how are you?
    Bob-->>Alice: Great!
    Alice-)Bob: See you later!
```

Qiita での mermaid の注意事項として、mermaid という単語を「見出し」として使用できないという制限があるため注意しましょう。

cf. 「mermaid」を見出しに使用できない

同じシーケンス図の内容ですが、出力された図をマウスで触っていただくと、PlantUML は画像となっており、mermaid はテキストが選択できることが分かると思います。
これは Qiita 上だけではなく、VS Code で拡張機能を使用して生成した場合でも同様になります。

PlantUML.2

エイリアスやアクターなども問題なく対応されています。

```plantuml
actor Alice as A
participant Bob as B

A->>B: Hello Bob, how are you?
B->>A: Great!
```

mermaid.2

```mermaid
sequenceDiagram
    actor A as Alice
    participant B as Bob
    A->>B: Hello Bob, how are you?
    B->>A: Great!
```

PlantUML.3

Qiita 上でも並列 par、分岐 alt、条件 opt、繰り返し loop、中断 break が記述できます。

```plantuml
par Alice to Bob
    Alice->>Bob: Hello guys, how are you?
    alt is sick
        Bob->>Alice: Not so good :(
    else is well
        Bob->>Alice: Feeling fresh like a daisy
    end
else Alice to John
    Alice->>John: Hello guys, how are you?
    opt Extra response
        John->>Alice: Thanks for asking
    end
    loop Additional response
        Alice->>John: You're welcome.
        break 3 times
            John->>Alice: Don’t mention it.
        end
    end
end
```

mermaid.3

mermaid の場合、Qiita 上では並列 par、分岐 alt、条件 opt、繰り返し loop は記述できますが、中断 break はエラーとなるようです。

```mermaid
sequenceDiagram
    par Alice to Bob
        Alice->>Bob: Hello guys, how are you?
        alt is sick
            Bob->>Alice: Not so good :(
        else is well
            Bob->>Alice: Feeling fresh like a daisy
        end
    and Alice to John
        Alice->>John: Hello guys, how are you?
        opt Extra response
            John->>Alice: Thanks for asking
        end
    end
```

PlantUML.4

背景色も標準の方法で対応できます。

```plantuml
par Alice to Bob
    Alice->>Bob: Hello guys, how are you?
    alt is sick
        Bob->>Alice: Not so good :(
    else is well
        Bob->>Alice: Feeling fresh like a daisy
    end
else Alice to John
    Alice->>John: Hello guys, how are you?
    opt Extra response
        John->>Alice: Thanks for asking
    end
    loop Additional response
        Alice->>John: You're welcome.
        break 3 times
            John->>Alice: Don’t mention it.
        end
    end
end
```

mermaid.4

mermaid でも背景色を設定することができますが PlantUML のように枠全体を塗るようにはなりません。

```mermaid
sequenceDiagram
    par Alice to Bob
        rect rgb(173,216,230)
            Alice->>Bob: Hello guys, how are you?
            alt is sick
                rect rgb(140, 230, 140)
                    Bob->>Alice: Not so good :(
                end
            else is well
                rect rgb(0, 128, 128)
                    Bob->>Alice: Feeling fresh like a daisy
                end
            end
        end
    and Alice to John
        rect rgb(255,182,193)
            Alice->>John: Hello guys, how are you?
            opt Extra response
                rect rgb(244, 164, 96)
                    John->>Alice: Thanks for asking
                end
            end
            loop Additional response
                rect rgb(221, 160, 221)
                    Alice->>John: You're welcome.
                end
            end
        end
    end
```

まとめ

以上、ごく簡単になりますが Qiita で PlantUML と mermaid のシーケンス図を記述比較をしてみました。

出力結果だけを見るとやはり mermaid の方がモダンな印象を受けますが、細かい記述をしたい場合は PlantUML に一日の長があるように思われます。

ただ、Qiita 独自ではありますが、break のように使えない機能もあるようなので、詳細まで使い込んでいった場合にどこかで引っ掛かる可能性もあるため、ツールやエディタなど環境次第によって選択肢が変わるかもしれません。

シンプルにまとめたい場合は mermaid、本格的に描き込みたい場合は PlantUML というように用途に合わせて変えるのもありかもしれませんが、資産を活かせなくなりそうなので微妙でしょうか。