はじめに
この記事はHRBrain Advent Calendar 2022 カレンダー2の8日目の記事です。
こんにちは！株式会社HRBrainでエンジニアをしているZamaです。
プロダクト開発の様々な場面で色々なドキュメントを作成すると思いますが、正直大変だったり面倒くさかったりしますよね...
しかし実装前の認識合わせや既存の設計や機能の確認などにドキュメントは書いておいた方がいいのも事実。
そこでドキュメント作成において図を楽に追加できるmermaidを紹介します！
※以下の内容は2022年12月8日時点のものになります。
mermaidとは
mermaidとは、MarkdownにインスパイアされたJavaScriptベースのダイアグラム・チャート作成ツールです。
Markdownのコードブロック内に図をテキストとして書いていきます。
GitHub、Qiita、Notionは標準で対応していて、Visual Studio Codeには拡張機能があります。
百聞は一見に如かずということで、いくつか例を見ていきましょう！
フローチャート
まずはフローチャートです！
開発タスクのステータス遷移を作ってみました。
簡単かつ楽ですね。
上がMarkdown内の記述、下がそれを元に生成された図になります。
flowchart TD
A[ToDo]--実装開始-->B[Implementing]
B--実装完了 PR作成-->C[Waiting For Review]
C--レビュー開始-->D[In Review]
D--Approved テスト環境作成-->E[Ready To Test]
E--テスト開始-->F[Testing]
F--テストOK-->G[Tested]
F--テストNG-->H[Test Failed]
H--修正開始-->B
G--PRマージ-->I[Done]
シーケンス図
次はシーケンス図です！
ユーザー登録時の処理の流れを簡単に作ってみました。
最初に登場人物を、それから処理をつらつらと書いていくだけです。
sequenceDiagram
participant User
participant App
participant Server
participant Database
User->>App: ユーザー登録ページを開く
App->>User: ユーザー登録フォームを表示する
User->>App: メールアドレスとパスワードを入力し、登録ボタンを押す
App->>Server: POST ユーザー登録API
Server->>Database: Insert メールアドレス, パスワード
Database->>Server: OK
Server->>Server: ログイン処理
Server->>App: 200 OK
App->>User: ダッシュボードページを開く
ER図
最後の例はER図です。
会社 - 部署 - 従業員というモデルを作ってみました。
配置を自由にできないという問題はありますが、社内資料としては十分なレベルです。
erDiagram
COMPANY ||--|{ DEPARTMENT: has
EMPLOYEE ||--|{ COMPANY: belongsTo
EMPLOYEE ||--|{ DEPARTMENT: belongsTo
COMPANY {
string name
string address
string telephoneNumber
}
DEPARTMENT {
string name
}
EMPLOYEE {
string firstName
string lastName
date birthDay
}
その他
他にも以下のようなものがあります！
聞いたことがないものもありますね...
まとめ
Markdown内に図を作成できるmermaidをご紹介しました！
文章やリスト、テーブルだけでは表現に限界があるので、こういった図を追加できるとドキュメントがより良いものになりますね！
しかも簡単です！
また、テキストとして定義するので、Gitで管理すればバージョン管理や差分の確認もできます。
ぜひ業務で使ってみてください！
We are hiring!
株式会社HRBrainでは、Power to the peopleを合言葉に多種多様な人事課題を解決するプロダクトを開発・運営しています。
日本の労働環境を良くしてやるぜ！みんなが元気に活躍できる社会にしてやるぜ！
そんな熱い気持ちを持った方、一緒に働きませんか？
皆様のご応募をお待ちしております！