Visual Studio Codeでソフトウェア設計書(Word文書)を書く環境を作る(概要)

2019/05/18 tomizo_no.2

目次
はじめにソフトウェア設計書を書くための条件必要な拡張機能 Markdown Preview Enhanced Prettier - Code formatter markdownlint PlantUML Markdown All in One 必要なソフトウェア Pandoc Imagemagick graphviz Java まとめ

はじめに

Visual Studio Code(VSCode)は、Microsoftが提供している無料で軽量、かつ強力なコードエディタです。
VSCodeは非常に多彩な設定ができることから、ソフトウェア開発を行うにあたっては、ソースコードを書いたりデバックしたりするだけでなく、うまく拡張機能を使えば、ソフトウェアの設計書まで作ることができます。
今回は、VSCodeでMarkdownとUMLを使ってソフトウェア設計書を書けるようにすることを目的とし、最終的にはMicrosoftのWord形式のファイルを生成する方法の概要を紹介します。

ソフトウェア設計書を書くための条件

ソフトウェアの設計書を作成するにあたっては、多くの方がソフトウェアの設計書をWordやExcelなどを使用して作成していると思います。
これらのオフィスツールは、文章や図を書くには非常に有用で、リッチな書式や図表による表現が可能です。
しかしながら、複数人で設計書を書こうとすると、どうしても差分やマージや履歴の管理など、細やかな変更管理が必要となりますが、現状、これらのオフィスツールは、こういった管理がイマイチなところがあります。
一方でソフトウェアのソースコードは、GitHubやGitLabなどを活用すれば、差分やマージや履歴が細かく管理できます。
そこで今回は、リッチな書式や図表による表現の優先度を低くし、テキストだけでソフトウェアの設計書を書けるような環境を作っていきます。
テキストだけでソフトウェア設計書を書くための条件は以下の通りです。
・テキストのみで書くため、リッチな書式は使わない
・図面をコードで書く
・開発環境と同じ環境で設計書を書く
・完成した設計書はWord形式で出力する
・作成したテキスト(コード)は、Gitで管理する

上記のような条件でソフトウェアの設計書を作成するために、ここでは、冒頭にも述べた軽量かつ強力なコードエディタであるVSCodeをベースとして環境を構築していきます。文章や表部分はMarkdownで記述し、図はUMLで記述します。

必要な拡張機能

VSCodeは、拡張機能(Extension)により、様々な機能をアドオンすることができます。
今回は、テキストだけでソフトウェア設計書を書くために、MarkdownとUMLに関する以下の拡張機能を使います。

Markdown Preview Enhanced

標準のMarkdownのプレビューでは図はイメージだけしか使えません。しかし、Markdown Preview Enhancedを使うと、PlantUMLというテキストだけで図が描ける拡張機能をMarkdownの中に含めることができ、さらにHTMLやPDFやWordなどの形式で出力できるようになります。
今回の環境ではVSCodeの次に重要な必須の拡張機能です。

PlantUML

図をテキストで描くために必要な拡張機能です。名前の通りUMLを描くことが目的ですが、ブロック図のような図も描くことができます。

Prettier - Code formatter

コードフォーマッタです。「Shift」+「Alt」+「F」のショートカットキーでドキュメントを整形してくれる拡張機能です。

markdownlint

その名の通り、Markdownのlintツール(書式のルールをチェック、指摘するツール)です。

Markdown All in One

Markdownのコードアシストといったところですか。
改行時に次のコードを入れてくれたりしてくれる拡張機能です。

上記のようにいろいろな拡張機能を使いますが、主要な拡張機能は、Markdown Preview EnhancedとPlantUMLです。その他は、Markdownをより効率的に記述するための補助機能です。

必要なソフトウェア

Markdown Preview Enhancedは、プレビューした結果をHTMLやPDFやWordなどの形式に出力することができますが、Word形式のファイルに出力するために、以下のソフトウェアをインストールする必要があります。また、PlantUMLを動かすためのソフトウェアもインストールする必要があります。