今の会社ではドキュメントを書いたりするのにDocbaseを使っています。
DocbaseはMarkdownでドキュメントを描くのですが、図を描いたりするのにPlantUMLやdraw.io等の記法が使えます。 様々な可視化に便利なので、これを活用して日々図を描いています。 今回は、どんなものを描いているのか、実例を紹介します。(そのものを公開はできないので、一部改変してますが)
PlantUMLとは
今回紹介するのは PlantUML です。UML以外にも多彩な図を描くことができるツールです。 作成されたシーケンス図などを目にする機会は結構多いのではないかと思います。
尚、今回紹介する使い方は、ガチのUMLとしてではなく可視化のツールとして使っているので、それはUMLとしてどうよ、、、みたいなツッコミは受け付けていません。 あくまで、可視化する時の参考、として見てもらえればと思います。
ちなみに、はてなブログではPlauntUML記法には対応していないので以下の例は試せないですが、VS Codeの Markdown Preview Enhanced 拡張を使えば確認できます。
UMLダイヤグラム
シーケンス図
処理の流れを表すのに使っています。 ソースコードの処理の流れなんかを描くことが多いですが、こんなふうにワークフローを描いたりもします。
ソースはこんな感じです。
@startuml title 記事作成から公開までのワークフロー\n actor Editor control Heroku database PostgreSQL actor Authorizer control "AWS S3" autonumber group 記事作成\n* プレスリリース\n* メディア実績\n* お知らせ Editor -> Heroku: [新規作成] ボタンクリック Heroku --> PostgreSQL: 記事保存 Editor -> Heroku: [承認申請] ボタンクリック Heroku --> Authorizer: 承認申請通知 end ... group 記事承認 Authorizer -> Heroku: [修正依頼] ボタンクリック Heroku --> Editor: 修正依頼 Editor -> Heroku: [承認申請] ボタンクリック Authorizer -> Heroku: [承認] ボタンクリック(Heroku上で公開) Editor -> Heroku: Heroku上で確認 end ... group 記事公開 Authorizer -> Heroku: [S3に公開] ボタンクリック Heroku --> "AWS S3": サイトにデプロイして公開 Editor -> "AWS S3": サイト上で確認 end @enduml
コンポーネント図
コンポーネント間の関係を示したい時に使っています。 この例は上記のシーケンスをどういうコンポーネントで実現しているかを説明する為に描いたものです。
ソースはこんな感じです。
@startuml title 記事作成から公開まで\n actor Developer component GitHub component Heroku #ccccff component S3 #ffccaa component Cloudfront #ffccaa Developer -> GitHub: masterにpush GitHub -> Heroku: build Heroku -> S3: deploy\n 静的ページに変換 Developer - Heroku: 表示確認 S3 -- Cloudfront: 静的website公開 Cloudfront - Developer: 表示確認 @enduml
アクティビティ図
バッチ処理をドキュメント化する時の流れを描く時に使っています。
ソースはこんな感じです。
@startuml title 処理アクティビティ\n start :実績値算出処理; :予想値算出処理; :年月別サマリー算出処理; end @enduml
その他の図
ガントチャート
変わり種ですが、こんなものも描けます。
プロジェクト管理ツールなりExcelなりを使ったほうが良いじゃんというのはもっともなのですが、 そういうものを使わずにドキュメントだけでぱっと表現したいときもたまにある訳で。 進捗実績%も表現できるので、簡易的なものとしては十分使えるかなと思っています。
ソースはこんな感じです。
@startuml language ja title 開発環境 Project starts 2022-03-01 [1. 事前検討 - 担当A] starts 2022-03-01 and ends 2022-03-02 [1. 事前検討 - 担当A] is 100% completed [2. 基本設計書作成 - 担当A] starts 2022-03-03 and ends 2022-03-09 [2. 基本設計書作成 - 担当A] is 10% completed [3. 詳細設計書作成 - 担当A] starts 2022-03-10 and ends 2022-03-16 [3. 詳細設計書作成 - 担当A] is 0% completed [4. 実装 - 担当A] starts 2022-03-17 and ends 2022-03-25 [4. 実装 - 担当A] is 0% completed [5. テスト仕様書作成 - 担当A] starts 2022-03-28 and ends 2022-03-29 [5. テスト仕様書作成 - 担当A] is 0% completed [6. 単体テスト - 担当A] starts 2022-03-30 and ends 2022-04-05 [6. 単体テスト - 担当A] is 0% completed [7. 結合テスト - 担当A] starts 2022-04-06 and ends 2022-04-12 [7. 結合テスト - 担当A] is 0% completed [10. QA/課題管理作成 - 担当B] starts 2022-03-03 and ends 2022-03-07 [10. QA/課題管理作成 - 担当B] is 80% completed [11. 基本設計書内部レビュー - 担当B] starts 2022-03-10 and ends 2022-03-11 [11. 基本設計書内部レビュー - 担当B] is 0% completed [12. 詳細設計書内部レビュー - 担当B] starts 2022-03-17 and ends 2022-03-18 [12. 詳細設計書内部レビュー - 担当B] is 0% completed [13. コードレビュー - 担当B] starts 2022-03-28 and ends 2022-03-29 [13. コードレビュー - 担当B] is 0% completed [14. テスト仕様書レビュー - 担当B] starts 2022-03-30 and ends 2022-03-31 [14. テスト仕様書レビュー - 担当B] is 0% completed @enduml
ファイル内容の可視化
PlantUMLではJSONとかYAMLの構造を可視化する機能があります。 ファイルを見ているだけだと分かりづらい設定値などの構成も簡単に可視化できるので、個人的に愛用しています。
JSON
JSON、APIの戻り値とかでよく使われますね。 以下はAzure CosmosDB(MongoDB互換ドキュメントデータベース)のあるコレクション構造を可視化した例です。
ソースはこんな感じです。
@startjson
{
"_id" : "",
"id" : "",
"createdAt" : {
"$date" : ""
},
"updatedAt" : {
"$date" : ""
},
"__v" : 0
}
@endjson
YAML
YAMLはKubernetesの各種設定等で使われますね。 以下はredisのConfigMapのYAMLを可視化したものです。
ソースはこんな感じです。
@startyaml
apiVersion: v1
data:
master.conf: ""
redis.conf: ""
replica.conf: ""
kind: ConfigMap
metadata:
creationTimestamp: ""
labels:
app: ""
chart: ""
heritage: ""
release: ""
name: ""
namespace: ""
resourceVersion: ""
selfLink: ""
uid: ""
@endyaml
まとめ
こうやって見てみると、PlantUMLって色々な図が描けて便利ですよね。 テキストで記述していくものなので、変更やバージョン管理も簡単です。 なんとなくいい感じに図を描きたいなと言う時に使ってみると、今より少しだけわかり易いドキュメントが書けるかもしれません。 自分の脳内整理や可視化に使ってみるのもいいと思います！
