はじめに

こんにちは。NTTテクノクロスの野村（@CorydorasNomu）です。この記事は「NTTテクノクロスAdvent Calendar 2024（シリーズ2）」の 19日目の記事になります。

ウェブアプリケーションやシステム開発のプロジェクトでは、クライアントとの円滑なコミュニケーションが重要です。しかし、技術的な内容や複雑な仕様を正確に共有することは、簡単ではありません。そこで注目されるのが PlantUML です。
今この記事を読んでいる皆さんは、「なにを今さら、そんなこと誰でも知ってるし使ってるよ」と思われるかもしれません。はい、筆者もそう思っています。しかし最近気づいたのですが、どうやらそうでもないらしい。
なので本記事では、PlantUML を活用することでクライアントとのコミュニケーションがどのように効率化できるかについて解説します。本記事がプロジェクトへの PlantUML 導入の契機になり、作業に携わるすべてのメンバの業務負担が少しでも軽減できれば嬉しいです。

PlantUMLの導入と使い方

先述のとおり、PlantUML は既に広く知られたツールです。
なので、導入方法や実際の使い方については既にネット上に十分な情報がありますので、細かい話はご自身で調べてみてください。
とりあえず以下の3つがあれば使い始められるはずです。

Visual Studio Codeでの作業は以下のとおり。

作業フォルダにテキストファイルを作成し、拡張子を .pu に変更する
上記のファイルに設計のコードを書き、Alt + D でプレビュー表示して内容を確認する
設計がFixしたら Ctrl + Shift + P でコマンドパレットを開き、export と入力する
サジェスト表示される Export Current Diagram を選択する
出力する設計画像の拡張子を選択すると、.pu ファイルの階層にフォルダが作成され、その中に設計画像が保存される

PlantUMLを活用するメリット

1. 視覚的な表現で仕様を明確化できる

クライアントと仕様を確認する際、複雑な条件の分岐やループ処理を日本語だけで記述しても、書き手の文章力や読み手の読解力によって認識の相違が生じます。しかしPlantUML を使えば、テキストベースで記述した仕様から下図のような視覚的なUML図を自動生成できるため、上述したような誤謬を最小限にすることができます。筆者は海外のメンバと一緒に仕事をして言葉の壁に苦労したので、このメリットはとても大きいと考えています。

2. リアルタイムでの変更が容易である

PlantUML を使用すると、テキストベースで設計を管理できます。そのため、プロジェクトの打ち合わせ中にクライアントからのフィードバックがあった場合、その場でコードを編集して即座に新しい設計図を生成・共有することで、誤解や認識の相違が原因の手戻り作業を減少させることができます。

3. 作業コストを削減できる

テキストベースで設計を管理するとで、作業コストの削減を期待できます。

設計図の履歴管理
Gitなどのバージョン管理ツールと連携することで、簡単に変更履歴を追跡できます。WordやExcelでもそうしたことは可能ですが、テキストベースのファイルと比べると、やはり変更差分の視認性という点で後者が優れます。標準化されたルールに沿ったコミットメッセージの形式を採用すると、変更履歴のトレーサビリティは更に向上します。レビュー記録票を別途Excelで書き起こしたり、仕様を確認するためにファイルサーバで過去の記録票を探し回るといった作業は最小化して、「良いものをつくる」ことに注力しましょう。
ドキュメント生成との統合
PlantUML を Markdown と組み合わせてドキュメントを生成することで、その作成とメンテナンスの作業効率が向上します。Markdown に設計図の画像ファイルへの参照さえ記述しておけば、独立した .pu の設計ファイルを修正するだけで最新の設計をドキュメントに反映することができます。ブラウザで GitHub や GitLab のリポジトリを表示したとき、Markdown を自動でレンダリングしてくれるので「今の最新版はどのファイル？」といった確認作業が不要になり、クライアントとの設計情報の共有にかかる工数も削減できます。

ラクして「伝わる設計」を

PlantUML を使った設計により仕様を視覚化し、誰もが直感的に内容を理解できるようにすることで、コミュニケーションの効率が向上します。また、テキストベースという特性上、その管理にかかわる作業も効率化され、プロジェクトを円滑な推進に寄与します。今回紹介した PlantUML のほかに、Mermaid もテキストベースのファイルで設計図を可視化するツールとして有名ですね。いずれにしろ、クライアントとのやり取りが多いプロジェクトほどこれまで述べてきたツールを活用する価値があります。まだこうしたツールを導入していないプロジェクトがありましたら、これからの設計業務での活用を前向きに検討してみてはいかがでしょうか。