見出し画像
Photo by tokiwafritz

Mermaidを使ってぷにあなフローチャートを描こう

Hokusai OKUTAMA

摘要

これは、トロオドンさんのアドベントカレンダー『トロオドン 怪文書 Advent Calendar 2023 - Adventar』の10日目の枠が空いていたのをいいことに勝手に参加した記事です。

本稿では、ドキュメントにおける図の意義踏まえつつ、テキスト形式によるすばやい作図を可能とするツールおよび記法である『Mermaid』について、他の作図ツールと比較しながら紹介します。
また、付録として、『Mermaid』を用いて作成した『ぷにあな』シリーズの派生図を掲載します。

おことわり

本稿は以下の読者を想定しています。

  • 業務や調査・研究で日常的にパーソナルコンピュータを使用している。

  • プログラミングやコンピュータに関する専門的な知識はない。

そのため、技術的、専門的に正確と言えない表現や説明をおこなっている可能性があります。
また、本稿は『Mermaid』のツールとしての側面を説明するものであり、本稿における『Mermaid』の使用とは、上記読者による使用を指します。
そのため本稿では、『Mermaid』に備わっている機能を無視して乱暴な説明、主張をおこなっている場合があります。

最後に、本稿ではややセンシティブな話題を取り扱います。
Noteのゾーニング機能が適用される想定ですが、「Hなのはダメ！死刑！」という読者、もしくはそのような環境にいる読者の閲覧は推奨しません。

Mermaidとは

『Mermaid』[^officialPage][^noQuoteAfter]とは、JavaScriptベースの作図ツールです[^aboutMermaid]。
テキスト形式の簡単なマークアップにより、様々な図を作成することができます。
サンプルとして、簡単なフローチャートの例を下に示します。

---
title: Simple flowchart
---
flowchart TD

openAmazon["amazonを開く"]
isHoppa{"ホッパの気分？"}
order["注文する"]

Start-->openAmazon
openAmazon-->isHoppa

isHoppa--"yes"-->ホッパを買う-->order
isHoppa--"no"-->RIDEを買う-->order

order-->End


この記述をMermaidに通すと、下の図を生成できます。

フローチャートサンプル

このように、Mermaidを使用すると、簡単なマークアップで作図をおこなうことができます。

作成可能な図には

  • フローチャート[^flowChart]

  • シーケンス図[^sequenceDiagram]

  • 状態遷移図[^stateDiagram]

などがあり、その他にも様々な、例えばGitのコミット履歴[^gitGraph]の図を作成する機能も備えています。

なぜ図が必要なのか

そもそも、なぜ図は必要なのでしょう。
Mermaidの公式ページは、作図[^diagramming]について次のように述べています。

Diagramming and documentation costs precious developer time and gets outdated quickly. But not having diagrams or docs ruins productivity and hurts organizational learning.[^refAboutMermaid]
〔ダイアグラム作成とドキュメント化は、開発者の貴重な時間を浪費し、すぐに時代遅れになります。しかし、ダイアグラムやドキュメントがないと、生産性が損なわれ、組織的な学習が損なわれます。〕[^transratedByTexTra]

上で述べられているように、作図作業にはそれなりの時間の消費が必要です。
また、業務や調査・研究などの進めるうち、図式化[^diagram]した内容に変更の生じることがありますが、必ずしも更新のための時間を確保できるできるとは限りません。
そのため、図の内容が最新の状況に一致しなくなることがあります。
だからといって、図を一切使用しないで業務や調査・研究の成果物を作成することは現実的ではありません。
もし、業務や調査・研究において、図の一切ない成果物を作成したとすれば、公式ページでも述べられているように「生産性が損なわれ、組織的な学習が損なわれ」てしまうことは容易に予測されます。
簡単に言うと、図がなければ、誰も読みたがらず、読みずらく、そしてつまらない資料や論文になってしまうのです[^likeThis]。
業務や調査・研究において、図は必須だと言えるでしょう。

なぜテキスト形式で作図をするべきなのか

ここまで、図式化は業務や調査・研究に必要である一方で、作図はそれらの活動の妨げとなってしまうことを説明してきました。
では、なぜテキスト形式で作図をするべきなのでしょうか。

公式ページでは、前掲の引用箇所で指摘した図式化および作図の課題[^thisProblem]について、次のように述べています。

Mermaid addresses this problem by enabling users to create easily modifiable diagrams, it can also be made part of production scripts (and other pieces of code).[^refAboutMermaid]
〔Mermaidは、ユーザーが簡単に修正可能なダイアグラムを作成できるようにすることで、この問題に対処します。また、プロダクションスクリプト(およびその他のコード)の一部にすることもできます。〕[^transratedByTexTra]

公式ページの述べる通り、Mermaidによって作成した図は簡単に変更することができます。
Mermaidによる図の変更とは、テキストのマークアップを変更し、要素同士の論理的な関係を更新するということです。
先に掲載したフローチャートの分岐を変更してみます。

---
title: Simple flowchart
---
flowchart TD

openAmazon["amazonを開く"]
whitchIs{"どの気分？"}
order["注文する"]

Start-->openAmazon
openAmazon-->whitchIs

whitchIs--"ホッパ"-->ホッパを買う-->order
whitchIs--"RIDE"-->RIDEを買う-->order
whitchIs--"G-PRO"-->G-PROを買う-->order

order-->End

変更後の図は下のようになります。


フローチャートサンプル 変更後

線を引き直したり、図の大きさを揃えたり、配置を調整する必要はありません。
必要なのは、分岐のテキストを変更し、選択肢を追加することです。
また、Mermaidではテキスト形式で図を作成（記述）するため、原理上テキストファイル編集が可能なソフトウェアは全てMermaidの編集ソフトとして利用できます。
これは実質的に、現代のほぼ全てのコンピュータ上で作図が可能なことを示しています。

その他、テキスト形式（≒テキストファイル）で作図をおこなう利点として、以下のものが挙げられます[^officeSuiteDemerit]。

  • 『Git』などのバージョン管理ツールと相性がよい。

    • Mermaidで作成する図はテキストファイルとして保存するので、変更箇所や変更内容を容易に差分比較することができます。

  • ファイルサイズが比較的小さい。

    • 図の情報は入力したテキストのみなので、保存時や送信時にかかる時間が短縮されます。

    • また、テキストをコピー&ペーストし、チャットアプリなどですばやく共有することもできます。

  • 作業環境への依存が比較的少ない。

    • テキストファイルがほぼ全てのコンピュータ上で編集可能であることは先に述べましたが、これは、特別な環境（OS、アプリケーション、ライブラリなど）の用意がほとんど必要ないことも意味します。

ところで、筆者はこれまで以下のツールを使用して作図をおこなっていました[^notDiagrammingSoft]。

  • LibreOffice

    • Calc

    • Impress

  • Microsoft

    • Excel

    • PowerPoint[^drawSVG]

上に挙げたツール[^officeSuite]を使用して作図をおこなっている方は少なくないと思われます[^ignoreProDiagrammer]。
本稿では、これオフィススイートを用いて作図することを否定しません。
なぜなら、オフィススイートで作図することにも利点があるからです。

オフィススイートで作図をおこなう利点として、以下のものが挙げられます[^mermaidDemerit]。

  • 直感的である。

    • セルに枠線を付けたり、シェイプ（図形）をドラッグ&ドロップで配置したりなどの直感的な操作で作図ができます。

  • 高品質な図を作れる。

    • シェイプごとに色を変える、強調したい文字だけフォントを変えるなど、細かな調整ができます。

  • 慣れ親しんでいる。

    • 業務や調査・研究において作図に限らず使用するので、操作を知っています。

上で挙げたように、オフィススイートによる作図にも利点はあります。
個人で使うだけの図であれば、不便を感じることは少ないかもしれません。
しかし、業務や調査・研究を複数人で協同しておこなう場合はどうでしょう。
例えば、以下のような課題が発生すると考えられます。

  • オフィススイートのライセンスを所有していないメンバーがいるかもしれません[^meToo]。

    • 自身もしくはメンバーが同時に複数の業務や調査・研究に携わる場合、異なる環境それぞれにツールが必要だとしたら、それだけライセンスと導入の負担が増えてしまいます。

  • 図に大きく変更のあった場合、編集に時間がかかってしまい、最新の情報をメンバーに通知するのが遅くなるかもしれません。

    • 通常、業務や調査・研究が進むほど扱う情報も増加するので、遅れはどんどん広がってしまいます。

  • メンバーが変更した図を変更前と比較しようとすると、まるで間違い探しのようになってしまうことでしょう。

    • バージョン管理ツールの差分比較機能は、オフィススイートが生成するファイルの形式には対応していないことがあります。

Mermaidは「ユーザーが簡単に修正可能な」[^refAboutMermaid]作図ツールであり、上記の課題の解決に寄与することができます。
図の情報はテキスト形式で作成、保存するので、バージョン管理ツールを利用することでメンバーの変更内容を容易に差分比較することができます。
また、バージョン管理ツールによっては、複数のメンバーによる異なる変更を統合することも可能です。
この機能を利用すると、だれかがファイルを開いている間、ほかのメンバーは待つ必要なく同時に変更をおこなうことができ、時間とメンバーの能力より活かすことができるでしょう。

「マークアップ」と聞くと、プログラミングのように専門的な知識が必要なように感じられるかもしれません。
ですが、公式ページが以下のように述べる通り、Mermaidのマークアップはすぐに習得可能です。

Mermaid allows even non-programmers to easily create detailed and diagrams through the Mermaid Live Editor[^aboutMermaidLiveEditor].
〔Mermaidを使用すると、プログラマでなくても、Mermaid Live Editorを使用して詳細な図を簡単に作成できます。〕

プログラミングの知識がなくても、Mermaidはするに使えるようになるはずです。
また、『Mermaid Live Editor』などのサービスを利用することで、自身のコンピュータにツールを導入することなく、すぐに使用を始めることも可能です。
また、公式サイトのドキュメント[^mermaidDocument]が充実しており、実際の図例を見ながらマークアップの記号を探すことができます。

Mermaidとオフィススイートを併わせて使用する

ここまで、Mermaidとオフィススイートを比較しながら、Mermaidを使用することの利点について説明しました。
しかし、Mermaidも万能ではありません。
先にオフィススイートの利点を挙げましたが、この内「直感的である」点と「高品質な図を作れる」点については、特にMermaidの苦手とする点だと言えます[^maniacCustom]。
情報共有のため業務や調査・研究のメンバー間で使用する成果物であれば、Mermaidによる作図で要求を満たせても、外部に提出・発表する成果物には追加の説明が必要な場合があります。
また、デザイン性の高い、グラフィカルな成果物の作成は、Mermaidのみでの作図では難しいことがあります。

そこで本稿では、Mermaidとオフィススイートを併わせて使用することを提案します。
例を以下に示します。

  • Mermaidで作成した図を『PowerPoint』のスライドに挿入する。

    • Mermaidを利用することで、シェイプで追加した矢印の向きや文字の大きさを調整するといった作業負担が軽減されます。

  • 『Excel』の集計結果を関数で処理し、Mermaidのマークアップとして使用可能な文字列を生成する。

    • セルの値をコピー&ペーストすることで、簡単に集計結果を図式化できます。

    • 『Excel』のグラフ機能でもよいのですが、目盛りなどに細かくこだわらない場合はコピー&ペーストで図を生成することができます。

  • Mermaidで作成した図を取り込み、オフィススイートのシェイプでさらに情報を追加する。

    • 図の項目や名称についての解説、注目してほしい箇所への矢印マークなどを付与することで、Mermaidのみでは難しい表現や情報の追加が可能です。

上に挙げた例のように、Mermaidとオフィススイートを併わせて使用することで、両者の長所を活かした成果物が作成可能となります。
マークアップに習熟しないうちに、いきなり全ての作図をMermaidに置き換えることは、生産性の面からも望ましいとは言えません。
まずはフローチャートからMermaidで作成するなど、それぞれの業務や調査・研究に合わせて少しずつ活用して欲しいと思います。

まとめ

本稿では、テキスト形式の作図ツールであるMermaidの紹介をおこないました。
また、作図が業務や調査・研究を遂行する上で必須であるが、同時に負担でもあることを説明し、テキスト形式での作図とオフィススイートによる作図とを比較することで、Mermaidの利用が業務や調査・研究によい影響を与えることを説明しました。
ただし、Mermaidも万能ではないので、オフィススイートと組み合わせた使用法についての提案をおこないました。

付録 ぷにあなフローチャート

来たる2023年12月24日(金)、『ぷにあなミラクルSPDX』の販売が開始されます。
この製品名称には、今まで発売されてきた『ぷにあな』シリーズの名称が引き継がれており、当然製品にもこれまでの製品の要素が盛り込まれた、大変豪華な1体になっていると思われます[^pleaseGimeMe]。
『ぷにあな』シリーズはこれまでにも多くの種類の製品が発売されています。
今回は、製品名に注目して、ぷにあなシリーズの派生をMermaid記法によるフローチャートで図式化しました。
本当はフローチャートで表現すべきではないかもしれませんが、面白かったのでここに掲載します。
なお、『ぷにあな』シリーズの商品情報については『大人のおもちゃとアダルトグッズの通販ショップNLS』[^nls]を参照していますが、表記の統一のため一部改めているものもあります。

図中の線は接続された商品間の関係性を示しています。
関係性については、商品名称および筆者の知識を元に判断しているため、誤りの含まれている可能性があります

線によって示されている関係性は以下の通りです。

  • 実線

    • 右側の商品が、左側の商品から直接派生したものであることを示しています。

  • 点線

    • 右側の商品が、左側の商品から間接的に派生したものであることを示しています。間接的とは以下の関係性のいずれかを指します。

      • 右側の商品と形状は異なるが、名称の一部を含んでいる。

      • 右側の商品と形状は異なるが、パッケージイラストから同一のキャラクターをコンセプトにしていると判断できる。

      • 右側の商品と品種は異なるが、名称の一部を含んでいる。

え？『ぷにあな』を知らない？オナホールだよ、オナホール。

---
title: ぷにあな派生図
---
flowchart LR

puni["ぷにあな"]

puniRe["ぷにあな:Re"]
puniReSoft["ぷにあな:Re ソフト"]

puniDX["ぷにあなDX"]
puniDXHard["ぷにあなDX ハード"]
puniDXSoft["ぷにあなDX ソフト"]
puniDXVerySoft["ぷにあなDX ふわとろ"]
puniDXNew["ぷにあなDX（形状記憶素材）"]
puniDXExtra["ぷにあなDX<極>"]

puniSPDX["ぷにあなSPDX"]
puniSPDXSoft["ぷにあなSPDX ソフト"]
puniMiracleSPDX["ぷにあなミラクルSPDX"]

puniMiracleDX["ぷにあなミラクルDX"]
puniMiracleDXWBTFD["ぷにあなミラクル爆乳DX"]

puniLowerDX["ぷにあな下半身DX"]

puniMeiki["ぷにあな名器"]
puniUnknown["ぷにあなナントカDX"]
puniRoid["ぷにあなロイドシリーズ1～8"]

puniJuice["濃厚ぷにあな汁"]
puniJuiceHot["濃厚ぷにあな汁 HOT"]
puniJuiceWhite["濃厚ぷにあな汁 白濁"]

subgraph "オナホール"
  subgraph "据え置き型"
    subgraph "据え置き型/オリジナル"
      puni---puniDX
      puni---puniRe
      puniDX---puniDXNew
    end
    puniRe---puniReSoft
    puniDX---puniDXHard
    puniDX---puniDXSoft
    puniDX---puniDXVerySoft
    puniDX---puniDXExtra
  end

  subgraph "トルソー"
    subgraph "トルソー/小型"
      puniDX---puniSPDX
      puniSPDX---puniSPDXSoft
      puniSPDX---puniMiracleSPDX
    end
    subgraph "トルソー/大型"
      puniDX---puniMiracleDX
      puniMiracleDX-.-puniMiracleSPDX
      puniMiracleDX---puniMiracleDXWBTFD
      puniMiracleDX-.-puniDXExtra
    end
  end

  subgraph "下半身"
    puniMiracleDX-.-puniLowerDX
    puniDX---puniLowerDX
  end

  subgraph "コラボ製品"
    puni-.-puniMeiki
  end

  subgraph "ランダム"
    puni-.-puniUnknown
  end

  subgraph "電動ホール"
    puni-.-puniRoid
  end
end
  subgraph "ローション"
    puni-.-puniJuice
    puniJuice---puniJuiceHot
    puniJuice---puniJuiceWhite
  end


『ぷにあな』シリーズ 派生フローチャート

サイズが大きいため、画像の文字が読めないほど縮小されていると思われます。
詳しく見たいという奇特な方は、Online FlowChart & Diagrams Editor - Mermaid Live Editorなどのサービスにコピー&ペーストすることで、拡大して確認することができます。

出典および参考

本文および脚注での紹介で情報の足るものについては省略しました。
本稿中に登場する商品、サービスおよびソフトウェアの名称および内容は、各権利者のものです。

参照はいずれも2023年12月21日(木) 18:00時点のものです。

書籍

  • 『日本国語大辞典 第二版』

    • 検索には『ジャパンナレッジ』[^japanKnowledge]で利用可能なウェブ版を使用し、脚注には『ジャパンナレッジ』が底本とした書籍の情報を記載しました。

<!-- footer note start -->
[^noQuoteAfter]: 以下、注記のない「Mermaid」とは、このツールのことを指します。
[^refAboutMermaid]: 公式ページ「About Mermaid」[^aboutMermaid]セクションからの引用。
[^transratedByTexTra]:『みんなの自動翻訳＠TexTra®』[^TexTra]を利用した機械翻訳であり、参考のために掲載。
[^diagramming]: 本稿では、「後述する『図式化』のための、線を引いたり文字を書いたりする実際の作業」を指す用語として用います。
[^diagram]: 『日本国語大辞典 第二版』[^nikkoku]によると「図式化」とは「物事の関係を説明するためにその概略を図に書いて示すこと」であると解説されています。本稿ではこの解説を拡張し、「物事の関係、状態を説明するため、その概略を図として示すこと」を指す用語として用います。
[^likeThis]: 本稿のように。
[^thisProblem]: 下の引用中の"this problem"〔この問題〕が指しているのは前掲の引用箇所。
[^exceptToShow]: ただし、自身のパーソナルコンピュータ上で作成した図を表示したり、画像などに出力するためには、環境を整える必要があります。これらの環境構築が不要なWEBサービスも存在します。
[^notDiagrammingSoft]: これらのツールは本来は作図をおこなうためのものではありませんが、様々なシェイプを組み合わせて作図ができます。
[^drawSVG]: 余談ですが、『PowerPoint』にはスライド中の図のみを画像ファイルとして出力する機能があり、出力形式も様々に用意されています。Webページに配置するオリジナルのアイコンの作成などちょっとした用途に大変重宝するので、おすすめです。
[^officeSuite]: 以下、「オフィススイート」と呼称します。
[^ignoreProDiagrammer]: 本稿は、参考資料としての図を作成する簡便なツールを紹介するものです。専用の作図ソフトを使用した厳密な作図は本稿の目指すものではないので、ここでは触れません。
[^mermaidDemerit]: これらは同時に、Mermaidが苦手とする点でもあります。すなわち、Mermaidで作図することのデメリットは、これらの点についての要求に応えにくいことです。
[^officeSuiteDemerit]: これらは、後述するオフィススイートでの作図が苦手とする点であり、これらの点についてMermaidにおよばないことがオフィススイートで作図することのデメリットの一部であると言えます。
[^meToo]: 実際、筆者の今回の執筆環境には『LibreOffice』『Microsoft Office』のいずれのオフィススイートもインストールされていません。
[^aboutMermaidLiveEditor]: Mermaid公式の作図用エディター[^mermaidLiveEditor]。ウェブブラウザ上でMermaidを利用した作図が可能です。
[^maniacCustom]: 公式ドキュメント[^configuration]を確認すると、様々な項目を設定することでMermaidの振る舞いが制御可能であることが分かります。しかし、本稿の目的は、専門的な知識がなくとも素早く作図可能なツールとしてのMermaidを紹介することですので、この点については省略します。
[^pleaseGimeMe]: 1体4万円ほどです。だれか買ってください。
<!-- footer note end -->

<!-- ref web page start-->
[^officialPage]: Mermaid | Diagramming and charting tool
[^aboutMermaid]: About Mermaid | Mermaid
[^flowChart]: Flowcharts Syntax | Mermaid
[^sequenceDiagram]: Sequence diagrams | Mermaid
[^stateDiagram]: State diagrams | Mermaid
[^gitGraph]: Gitgraph Diagrams | Mermaid
[^TexTra]: みんなの自動翻訳＠TexTra®
[^mermaidLiveEditor]: Online FlowChart & Diagrams Editor - Mermaid Live Editor
[^mermaidDocument]: Tutorials | Mermaid
[^configuration]: Configuration | Mermaid
[^japanKnowledge]: ジャパンナレッジ
[^nls]: 大人のおもちゃとアダルトグッズの通販ショップNLS
<!-- ref web page end -->

<!-- ref books start -->
[^nikkoku]: 日本国語大辞典第二版編集委員会・小学館国語辞典編集部編（2000－2002）『日本国語大辞典 第二版』小学館
<!-- ref books end -->