Mermaidがダイアグラム・アズ・コードを定着させた：シーケンス図はMarkdownの中のテキストになった

UMLはソフトウェア設計図を標準化しようとした壮大な試みだった。OMGは1997年にこれを承認し、ISOは2005年に採用した。しかしUMLは自らの重みで崩壊した。UML 2.2のドキュメントは1,000ページを超え、標準は重量級のCASEツールや負担の大きい事前作業と結びつき、2020年代までには賛成派も反対派も、事実上死んだことで一致していた。

ひとつの成果物だけがそれを生き延びた。シーケンス図である。コンポーネント間を流れるメッセージを表す単純な地図だ。生き残った人々はそれを描けたが、ツールが苦痛にしていた。BitHawkの開発者jessemsは、Lucidchartで図形をドラッグするのは遅くてもろく、将来の変更がレイアウトを台無しにすると感じていた。

転機はMermaidだった。図をプレーンテキストとして宣言するJavaScriptライブラリで、参加者、矢印、メッセージをMarkdownのコードフェンス内に書き、Markdownツールチェーンが描画する。著者はコードでコードを書くのは違和感があるだろうと思って試し、それから速く、苦痛がなく、美しいと分かった。彼はユーザーストーリーの実装計画にシーケンス図を埋め込み始め、ホットリロードでプレビューし、画像としてエクスポートしてHTMLフィールドに貼り付けた。

定着した理由は、図が普通のコード成果物になったことだ。文書化するストーリーの隣に置かれ、コードレビューで差分が取れ、描き直すのではなく一行の編集で更新され、Markdownが使える場所ならどこでも描画される。GitHub MarkdownはMermaidを標準でサポートしていると、Hacker Newsのスレッドのコメント投稿者たちは指摘した。Mermaidの創業者はこれを、Rational Rose時代のツールの硬直した複雑さに代わる、非公式な簡潔さと位置づけた。

図をコード成果物にすること。Markdownにテキストとして書き、レンダラーに描かせる。

図をタイプするのはドラッグするより速いため、作成コストはキャンバスでの作業から文書の隣の数行へと下がる。

テキストはコードのようにバージョン管理され差分が取れるため、図の更新はもろい描き直しではなくレビューでの一行の編集になる。

Markdownレンダラーはすでにどこにでもあるため、図はチームがすでに文書を読みコメントする場所に表示される。

UMLは複雑さを加えて死んだ。Mermaidは有用な成果物だけを残し、その周りのツールコストを取り除いた。

標準が生き残るのは、人々がすでに働いている場所でコストを削るときだ。勝つ図とは、文書にタイプでき、レビューで差分が取れる図である。

この投稿は2023年7月24日、Hacker Newsで207ポイントと111件のコメントを集めた。コメント投稿者たちは、GitHub MarkdownがMermaidを標準で描画することに触れ、PlantUML、d2、Graphvizと比較し、1回のインストールコマンドで描画するDocusaurusのようなMarkdownエコシステムを勧めた。著者はBitHawkでこのワークフローを続け、シーケンス図がMarkdownファイル内にある実装計画を起草し、記録にHTMLが必要なときはmermaid-cliで画像としてエクスポートした。