Help us understand the problem. What is going on with this article?

【mermaid.js】設計図をGitHub管理下に置く

More than 1 year has passed since last update.

設計図を伴う中規模以上の開発でまれによくあるのが次のような状況です。

  • 担当者が何かしらのツールを使って設計図を書き、画像をアップロードする
  • N回繰り返す:
    • 口頭で設計に関するレビューを受ける
    • 議事録を参照しながら設計図を更新し、画像を再アップロードする
  • どの画像が最新だったのか、変更履歴がどうなのか分からなくなってくる
  • 画像を作ってた担当者がいなくなり、画像のソースが失われる

これに対し、こうだったらいいな〜と前々から思ってたのは次のような状況です。

  • 設計図の画像ではなくソースがGitHubに上がっている
    • 変更履歴も残っているし、変更箇所もすぐ分かる
  • 設計のレビューは設計図のソースに対する行コメントを通じて行われる
  • それでいて画像はブラウザ上で簡単に閲覧できる

というわけで作ってみました → mermaid-for-github-chrome-extention
mermaid.jsのコードを元にブラウザ上で図を描画するChrome拡張です。
GitHubとGistに対応してます。

マークダウンに言語を"mermaid"としてコードブロックを書いて(グラフ定義は公式デモより引用)

# Johnの起床シーケンス

- JohnはAliceからの通信をtriggerに起床します
- Johnは起床後、Bobに通知を送ります

```mermaid
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts<br/>prevail...
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!
\```

ブラウザで開くと、コードブロック部分が描画された図に置き換わります。

sequenceDiagram

つまり設計書と設計図をマークダウンで書いてプルリクエストを発行し、
それに対して行レビューをもらうという方式が可能になります。
変更履歴の管理は通常のソースコードと同様になります。

ハッピーシステムデザイン!!


mermaid.js自体については次の記事が参考になります。

set0gut1
東京の野良プログラマです。 CEO, CTO, 代表取締役ではないです。 各種アカウント等 → https://set0gut1.com/
https://set0gut1.com/
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした