ドキュメントにこだわるなら、Mermaidを使えという話

プログラミングを仕事でし始めた頃、ドキュメントを書くなんてまるで頭にありませんでした。 まだ世の中に、スマートフォンがなかった時代もあり、ドキュメントは仕様書であり、設計書であり、マニュアルという認識の時代（自分の感覚ですが・・・）に ドキュメントを書くよりも、プログラムコードを書く方が生産性が高いとずっと考えていましたが、 自分1人で開発をしているのではなく、複数人で開発をすると、必ず何かしらの書面で情報共有をする（経歴や仕様決定を残す）必要が重要であることを思い知らされました。 そして、ドキュメントは、自分の身を守る重要な武器であると気がついた時から、ドキュメントに対する意識が大きく変わり、今に至ります。 自分のドキュメントに対して思考と、最近使って便利に思えた mermaidツールをご紹介したいと思います。

ドキュメントを上手に書くためにブログを書き始めた話

そうです、自分はそもそも文章を書くのが、とても苦手であり、書くこと自体が嫌だったんです。 学生時代に、国語の成績が良かったわけでもなく、本も読まない、作文なんて苦手中の苦手な状態でした。（いわゆるアホな子） ある時、ドキュメントを書きたいけど書けない自分に対して、とりあえず毎日ちょっとずつ仕事のドキュメントを書くというタスクをかしてみました。 1日１センテンスぐらいなら書けるでしょう。 ということで、最初はブログの程もなしてなくて、まとまりもなく、思った事を書いているだけの物書き作業をスタートしたんですが、 メモ帳から始まり、Webの色々なテキストが書けるサービスや、スマホアプリを使ってみましたが、結局行き着いた先は・・・ ドキュメントは、全体のまとまりから、内容のまとまり、とにかくまとまっていないと、とても読みにくいし、書くのも一気に書いた方がスピードもモチベーションも上がりやすいという事を理解しました。 ただし、ダラダラと、書籍ボリュームを書くというのも現実的じゃないので、1つのテーマがあれば、その中のセンテンスを小分けに１回で書くというのが、ブログの1記事分とちょうど同じぐらいだと考えて、 そういう趣旨でブログを書き始めたら、10年以上続ける事ができる、もはや趣味の様な領域になりました。 そして、結果的に、文章を書くことに対して、何の思考の抵抗もなく、むしろ書きながら色々な事を考えられるライター気質が身についた事に5年目ぐらいで自己認識する事ができたんですよね。

ドキュメントスキルはいろんな場面で求められる

プログラミングをしていると、多くの場合にGithubを使うケースは多いでしょう。 でも、誰かに何かの説明をする場面や、 そもそも、メールを書く時なども、ドキュメント能力が大きく求められないですかね？ もらったメールが、クドクドと長くて意味不明な言葉のられる、まるで内容が掴めないし結論が分かりにくいメールが送られてきたら、不快感しか残らないじゃないですか。 SNSでツィートする時や、特定の集団での告知文章を書く時なども、ドキュメント能力は非常に重要視されます。 正直、いい文章を書く人って、「いい人」の印象をもたれやすいですからね。 会社の採用面談をしているときに、自己アピールが上手な人と下手な人は、ほぼドキュメント能力に依存すると言ってもいいぐらいです。 ドキュメントに苦手な人は、他人からの人間判断が低く見積もられがちなので、この辺意識してみるといいかもですね。

ドキュメントに図を載せたくなったとき

ドキュメントを書き続けていると、写真や図を載せて、もっとわかりやすくしたいと思い始めたときに、 Githubが、mermaidというプラグインでドキュメントにフロー図などを表示できるという事を知りました。

mermaidについて

https://mermaid.js.org/ テキストで図が書ける、Javascriptライブラリです。 対応している図は、以下の様な種類があります。

1. フローチャート（graph）
2. シーケンス図（sequenceDiagram）
3. クラス図（classDiagram）
4. ガントチャート（gantt）
5. 状態遷移図（stateDiagram）
6. ER図（erDiagram）

mermaidデモ

[HTML] <script src="https://unpkg.com/mermaid@10.9.0/dist/mermaid.min.js"></script> <div class="mermaid"> graph TD A[スタート] --> B{条件} B -- Yes --> C[処理1] B -- No --> D[処理2] C --> E[終了] D --> E </div> これだけで、実装できてしまうなんて、Webサイトでも便利に使えそうですよね。

ビジュアルエディタもあるよ

Mermaid Live Editor このページに行くと、ビジュアルを確認しながら、図を書いていく事ができます。 種類切り替えも、ボタンひとつだし、出来上がったコードをコピペして使うこともできるので、こんな便利なツールないですよね。

コードエディタなどで使う

あたりまえですが、仕様書などのドキュメントは、図を入れたければ、エクセルやワードやパワポといった、Office製品を使うか、 それをPDFで出力してファイルとして扱う事が大半ですが、 この mermaidプラグインを使うと、テキストファイルだけで管理できるようになるので、 Githubリポジトリとして管理が可能になります。 GithubのREADME.md表示は、すでに mermaid ライブラリが適用されているので、ドキュメント内に書かれたコードが自動で図にされますが、 自分の使っているVScodeなどの場合は、プラグインをインストールする必要があります。 Webサイトで表示したい場合は、上記のCDNを使った方法で手軽に表示できるのですが、 Marpを使った、セミナー資料作成などの場合でも、VScode連動でかなり便利に使う事が可能になります。 Marp

あとがき

今回紹介したMermaidプラグインんお出力は、svg形式になっているので、軽いというのが理解できますね。 個人的には、もう少し見た目を改良して、いい感じにしたいので、svg用のCSSを書こうと思っています。 自分用のテーマが作れたら、唯一無二のドキュメント作成も可能になりますからね。 モチベーション爆上がり間違いなしでしょう！