VSCodeでMD&UML

エディター
2020.09.14

MD（Mark Down）とUML（Unified Modeling Language）を使って
スマートに設計作業を進めると作業効率が上がります。
この作業をVSCodeのテキストベースのみで行うことで
GUIで描画ツールを使ったり、テキストを埋め込んだりという煩わしさから解放されます。

UMLとは

ソフトウェアの開発・設計に用いられるモデリング言語とされており、
整理したい情報を図示（モデリング）し、認識の統一を図ることを目的としています。

情報を視覚化するというところがミソです。

アウトプットのしやすさ

認識の統一を図る為に、情報をモデル化して共有していくことが大事なのはわかりました。
一方で、このような資料を作成する事に作業時間を多く取られてしまうと
本来やりたいことに時間を掛けられなくなります。

大事なのは人によって書き方が様々になってしまうフリーハンドの資料ではなく
ある程度テンプレート化された図を素早くアウトプットすることです。

属人性のある資料を読むのは時間と体力を要します。
共通認識を持つのは作業効率UP、認識齟齬による手戻りを戻す事が狙いです。
資料の読解に時間を要しては本末転倒です。

そこでUMLの出番となります。
このUMLをいかに素早く作成できるか、
またアップデートしていけるかが大事になります。

VSCodeで記述したテキストから描画する

テキストベースで記述するメリットを挙げると

  1. テキストで記述できるので、図の整形に手間を取られる事が無い
  2. バージョン管理ツール（GitHubやSVN等）でも差分を取りやすくなる
  3. HTML出力も可能なので、そこからPDFやJPEG等にも変換可能

3つ目の出力はおまけ程度になりますが、１と２のメリットはとても大きいです。

図の整形に手間を取られない

Excelで作成する例を考えてみましょう

  1. 図形を選択
  2. 図形を配置
  3. 図形に文字を埋め込み
  4. 線などを追加して
  5. 更に説明文をセルに入力

これらの作業を行う為には、マウスとキーボードをフル活用する必要がありますね。
図形の配置バランスが気に食わなければ微調整が必要となります。
（位置調整に使える機能もありますが）
手数が多くなってしまうのがデメリットになります。

また、文字列を検索したい際に図形に記載されている文字は検索対象となりません。
（これもアドインを入れれば対応可能ですが。。。）

バージョン管理可能

編集前の図はどうなっていたのか、何が更新されたのか
元のバージョンに戻したい等の対応が容易になります。

何も考えずにGitHubで管理すればそれで終わりです。
テキストベースなのでサイズも抑えられますね。

UMLを作成する為の準備

実際にUMLを作成してその利便性を体感しましょう。
論より証拠。グダグダ説明するよりも、実際に生成される図を見て何を思うか。です。

UMLを作成するにあたって、VSCodeの環境を整えます。

導入するソフト

  1. PlantUML（VSCodeのExtension）
  2. Graphviz（online serverを使用することも可能）

PlantUMLを導入

VSCodeを起動して、Extensionをインストールしてください
「⌘ + Shift + x」でExtensions windowが開きます（Windowsは ⌘：Ctrlに読み替えて）

検索窓に「plantuml」を入力

Installボタンを押してExtensionsに追加してください

Graphvizを導入

MacだとbrewコマンドでInstallできますし、Windowsだったら公式サイトからzipファイルをdownloadしてください

brew install graphviz

online serverを使用する方法

⌘ + Shift + P で settings.json を開き、設定を追記します。

{
    "markdown-preview-enhanced.plantumlServer": "https://kroki.io/plantuml/svg/"
}

UMLを作成する

```plantumlでスタートするとそこからumlの記述エリアになります。

再度 ```を書けばそこまでがumlの記述として認識され、
それ以降は再びMarkDownの記法が有効になります。

シーケンス図

sample.mdにサンプルのUMLコードを記載しました。
Markdown Preview Enhancedを使ってプレビューを表示すると右下の図が表示されます。

```plantuml
@startuml
title 図1. sample

Client -> Server : request
Client <- Server : response

@enduml
```

この機能をうまく使えば設計書を全てMarkDownで記載する事もできます

以前、携わっていたプロジェクトの現場で
私はこのツールで処理フローなどを記載したHTMLを出力して設計書としていました。

noteを追加する

noteはtooltipのように図の脇にメモを貼り付けることができます。

```plantuml
@startuml
title 図1. sample

Client -> Server : request
note left
場所を指定する(left)
end note
note right
noteを書く事が可能(right)
end note
Client <- Server : response

@enduml
```

note 《表示位置 left / right》　　から始まって
end note　　　　　　　　　　　で終わる

間に挟んだ文章がノートの中に表示されます。
ちなみに、ノートの中に表も書けます。

note right
noteを書く事が可能(right)
| col1 | col2 | col3 |
|   aa |   bb | cc   |
end note

見た目を更に改善する

VSCodeを使ってMarkDownのプレビューが良い感じにできる記事を紹介しました
詳しくは下記リンクから覗いてみてください

[VSCode]Markdown PreviewをCSSで読みやすくする方法 part2
VSCodeのMarkdownPreviewって、便利だけどちょっと読みにくい時ってありますよね。見出しとか見分けがつかなかったりします。Markdownにスタイル（css）を適用して視認性を上げることで、より作業を効率化してみてはいかがで...
habataki-blog.com

今回はVSCode（Visual Studio Code）エディタでMarkDown（マークダウン）を更に進化させて、
図を取り入れた文書の作成方法を記事にしました。
下図のように、スタイルが当たると更に見やすくなりますね。