図から生きているドキュメントへ：Visual ParadigmのDevOpsパイプライン入門ガイド - Tech Posts Japanese - Latest Trends in AI, Software, and Digital Innovation

はじめに：陳腐化したドキュメントの終わり

ソフトウェアプロジェクトに一度でも携わったことがあるなら、「ドキュメント負債」の苦しみを知っているだろう。VisioやLucidchartで美しいアーキテクチャ図を何時間もかけて描き、開発チームがデータベーススキーマを変更したり新しいマイクロサービスを追加した瞬間に、その図がまったく陳腐化してしまうのを目の当たりにする。ドキュメントは負担になり、開発者はそれを信用しなくなる。

登場する生きているドキュメント—ドキュメントが自動生成され、継続的に更新され、実際のコードベースと完全に同期されたパラダイム。

From Diagrams to Living Documentation: Visual Paradigm’s DevOps Pipeline

このチュートリアルでは、以下の構築をガイドします。Visual Paradigm（VP）DevOpsおよびドキュメントパイプライン。静的な視覚モデルを自動化され、生きている知識ベースに変換します。このガイドの最後までに、デスクトップ設計ツール、AIアシスタント、CI/CDパイプラインを接続して、スムーズな「生きているドキュメント」ライフサイクルを構築する方法を理解できるようになります。

推奨されるツールと事前準備

このパイプラインに従うには、Visual Paradigmエコシステムおよび標準的なDevOpsツールへのアクセスが必要です：

Visual Paradigm デスクトップ版またはオンライン版：豊富なUML、SysML、BPMN図を作成するため。
VPチャットボット／AIアシスタント：自然言語のプロンプトを使って初期の図を生成するため。
Git：テキストモデルとコードのバージョン管理のため。
CI/CDプラットフォーム：GitHub Actions、GitLab CI、またはJenkins（このチュートリアルではGitHub Actionsを使用します）。
OpenDocs／PlantUML：テキストモデルを視覚的な出力に変換するため。

フェーズ1：設計レイヤー（アーキテクチャの把握）

パイプラインは、要件を把握し、システムアーキテクチャを設計する場所から始まります。Visual Paradigmは、モデルを設計するための3つの主な方法を提供しています：

VP デスクトップ：複雑なエンタープライズアーキテクチャ、UML、BPMN向けのフル機能の強力なツール。
VP オンライン：クラウドベースで共同作業可能なツールで、素早いベクターグラフィックやアジャイルな計画に最適。
VPチャットボット／AI：テキスト記述やユーザーストーリーから直接図を生成する会話型インターフェース。

現実的な例：ECサイトのチェックアウトフローの設計

新しい電子商取引プラットフォームのチェックアウトアーキテクチャを設計するという課題を想定してください。手動で図形をドラッグアンドドロップする代わりに、次の方法を使用できます。VPチャットボット以下のプロンプトを使用して：

「電子商取引のチェックアウトシステムのコンポーネント図を生成してください。Webフロントエンド、注文サービス、決済ゲートウェイ、在庫データベースを含める必要があります。」

AIは即座に構造図を生成します。裏では、この視覚モデルは標準的なテキスト構文（例：）を使って表現できます。PlantUML、これはVisual Paradigmがテキストモデリング機能としてネイティブにサポートしているものです。

以下は、AIが生成した設計を表すPlantUMLコードです：

PlantUML

VPasCodeでPlantUMLを編集

Plantuml Edit Plantuml in VPasCode

@startuml 電子商取引チェックアウトアーキテクチャ
!theme plain
skinparam componentStyle rectangle

package "フロントエンドレイヤー" {
  [Webアプリケーション] as Web
  [モバイルアプリ] as Mobile
}

package "バックエンドマイクロサービス" {
  [注文サービス] as Order
  [決済ゲートウェイ] as Payment
  [在庫サービス] as Inventory
}

database "PostgreSQLn(在庫DB)" as DB

' 関係
Web --> Order : REST API
Mobile --> Order : REST API
Order --> Payment : 取引処理
Order --> Inventory : 在庫確認/予約
Inventory --> DB : 読み取り/書き込み

@enduml

Edit Plantuml in VPasCode

VPasCodeでPlantUMLを編集

フェーズ2：抽象化レイヤー（VPasCode）

視覚モデルは人間にとっては優れていますが、機械はテキストが必要です。ここが VPasCode（Visual Paradigm as Code） ギャップを埋める場所です。

VPasCodeでは、図をソフトウェアコードとまったく同じように扱うことができます。

テキストモデリング： 図を人間が読みやすいテキスト（上記のPlantUMLコードなど）を使って定義します。
バージョン管理： これらの図の定義を .puml または .vpuc ファイルとして、アプリケーションコードと一緒にGitリポジトリに直接保存します。
SDK/CLI自動化： 視覚要素をプログラム的に照会または変更するために、Visual ParadigmのAPIを使用できます。

現実的な例：Gitへのコミット

図を孤立した形式で保存する代わりに、.pngファイルに、PlantUMLコードを以下のように保存します。checkout-architecture.pumlプロジェクトの/docs/architecture/フォルダ内に保存します。

git add docs/architecture/checkout-architecture.puml
git commit -m "docs: 初期チェックアウトアーキテクチャ図を追加"
git push origin main

これで、図はバージョン管理されます。開発者がOrder Serviceを変更した場合、同じプルリクエストでテキストファイルを更新します。

フェーズ3：自動化レイヤー（OpenDocs と CI/CD）

ここが魔法が起こる場所です。もはや図を手動でPDFやWordにエクスポートする必要はありません。代わりにOpenDocsとCI/CDパイプライン.

OpenDocs：モデルデータ（PlantUML/VPasCodeファイル）を読み取り、テキストテンプレートにマッピングするオープンスタンダードなドキュメント生成フレームワークです。
パイプライン統合：リポジトリの変更を監視するために、CI/CDツール（GitHub Actionsなど）を使用します。
自動トリガー：コードやモデルが変更されるたびに、パイプラインはドキュメントを自動的に再構築します。

現実的な例：GitHub Actionsワークフロー

以下は、アーキテクチャファイルが更新されたときにトリガーされる現実的な.github/workflows/build-docs.ymlファイルです。アーキテクチャファイルが更新されるたびに実行され、PlantUMLを使って図をレンダリングし、静的HTMLサイトにパッケージ化します。

name: ライvingドキュメントのビルド

# docs/architectureフォルダ内のファイルが変更されたときのみワークフローをトリガー
on:
  push:
    paths:
      - 'docs/architecture/**'
  workflow_dispatch: # 手動実行を許可

jobs:
  generate-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: リポジトリをチェックアウト
        uses: actions/checkout@v3

      - name: Javaの設定（PlantUML/VP CLIに必須）
        uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: OpenDocs/PlantUMLで図を生成
        run: |
          # PlantUML jarをダウンロード
          wget https://github.com/plantuml/plantuml/releases/download/v1.2023.10/plantuml-1.2023.10.jar -O plantuml.jar
          # アーキテクチャディレクトリ内のすべての.pumlファイルをSVG/PNGにレンダリング
          java -jar plantuml.jar -tsvg docs/architecture/*.puml

      - name: ライブドキュメントHTMLをコンパイル
        run: |
          # カスタムOpenDocsスクリプトまたはVP CLIコマンドで画像をHTMLテンプレートにラップすると仮定
          mkdir -p public/docs
          cp -r docs/architecture/*.svg public/docs/
          # メタデータと埋め込み図を含むindex.htmlを生成
          echo "<html><body><h1>ライブアーキテクチャドキュメント</h1>" > public/docs/index.html
          echo "<img src='checkout-architecture.svg' />" >> public/docs/index.html
          echo "</body></html>" >> public/docs/index.html

      - name: GitHub Pagesにデプロイ
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

フェーズ4：出力レイヤー（ライブドキュメント）

このパイプラインの最終製品は、あなたのライブドキュメントです。ソースオブトラース（あなたのコードとテキストモデル）から自動的に生成されるため、いつまでも最新の状態を保ちます。

単一の真実のソース：コード、ビジュアルモデル、テキスト説明は完全に同期されたままです。
フォーマットの柔軟性：パイプラインは、GitHub Pagesや社内WikiにホストされたレスポンシブなHTMLウェブサイト、コンプライアンス用のPDF、またはConfluenceに直接プッシュする出力が可能です。
動的メタデータ：高度な設定では、アクティブなシステムメトリクス、データ辞書、Jiraの要件追跡を、生成されたユーザー向けテキストに直接埋め込むことができます。

あなたのチームは今、美しい最新のURL（例：docs.yourcompany.com）を所有しており、ソフトウェアの正確な現在の状態を常に反映しています。

ステップバイステップの実装ワークフロー

要約すると、このエコシステムを維持するためにチームが毎日従うワークフローは以下の通りです：

ドラフト：VP Desktop/OnlineでUMLクラス図、コンポーネント図、またはBPMNプロセス図を作成する、またはユーザー・ストーリーから生成するようVPチャットボットに指示する。
エクスポート：プロジェクトのGitリポジトリ内に、VPasCode/PlantUMLテキスト形式で設計ファイルを保存またはコミットする。
ビルド：変更をGitにプッシュする。この操作により、CI/CDパイプライン（例：GitHub Actions）が自動的にトリガーされる。
生成：パイプラインはOpenDocs/PlantUMLを実行し、新しい図画像を抽出し、メタデータをコンパイルし、HTML/PDF出力を構築する。
公開：ツールは最新の更新されたライブドキュメントを、社内チームポータル、Wiki、または公開ドキュメントサイトにデプロイする。

結論：ライブドキュメントのマインドセットを受け入れる

ビジュアル・パラダイムのDevOpsパイプラインに移行するには、マインドセットの変化が必要です。ドキュメントはもはやスプリントの終わりにジュニア開発者に割り当てられる後回しのタスクではなくなります。むしろ、開発プロセスそのものの自動化された副産物となるのです。

以下の層を活用することで、デザイン層（VP DesktopおよびAI）、抽象化層（VPasCode）、自動化層（CI/CDおよびOpenDocs）、そして出力層（ライブドキュメント）により、文書化の負債を永遠に解消できます。図はようやくコードと同程度のスピードで進化し、チームに信頼できる単一の真実のソースを提供し、より良い意思決定と迅速なオンボーディングを可能にします。

小さなステップから始めましょう。1つのコアマイクロサービスを選択し、そのアーキテクチャをPlantUMLで記述し、Gitにコミットして、基本的なGitHub Actionを設定してレンダリングさせます。初めて「ライブドキュメント」が自動的に更新されるのを見た瞬間、手動での図作成に戻ることは二度となくなるでしょう。

参考

事例研究：VPasCodeによるソフトウェアアーキテクチャ文書化の加速――図をコードで表現する革命：AI対応の図をコードで表現する仕組みと自動レイアウト設計技術を活用して、コードと可視化のギャップを埋めるVPasCodeの事例研究。
Visual ParadigmによるVPasCode総合ガイド：VPasCodeのコア理念、ユーザーインターフェース、マルチエンジン対応、コラボレーションワークフローについての詳細な概要。
コードから明確さへ：VPasCodeとOpenDocsによるスムーズな図作成入門ガイド：AI駆動の文書化にVPasCodeとOpenDocsを活用する方法についてのチュートリアル。実用的なPlantUMLの例とパイプライン統合を含む。
VPasCodeマスタリング：マルチエンジン対応のAI駆動図をコードで表現する究極のガイド：VPasCodeの独自の利点、AIネイティブアーキテクチャ、マルチエンジン対応についてを網羅する上級者向けガイド。
図の保守を革命化する：VPasCodeのAI自動修正が構文の悩みを解消する方法：VPasCodeのAI駆動自動修正機能についての詳細な解説。構文エラーの自動検出と修正を実現。
Visual ParadigmのAIチャットボットとVPasCodeが、図作成の統合エコシステムとしてどのように機能するか：AIチャットボットによる迅速な生成と、VPasCodeによる正確な図の微調整を組み合わせた統合型2段階ワークフローの説明。
設計による明確さ：VPasCodeとGraphvizによるインフラ構造文書化の簡素化：インフラ構造の文書化をコードとして現代化するために、VPasCodeとGraphvizのDOT言語を活用する事例研究。
VPasCode：統合型図をコードで表現するプラットフォーム：公式機能ページ。対応図種類、マルチエンジン対応、リアルタイムプレビュー、エクスポート機能などを詳細に紹介。