見出し画像
Photo by ryonakano

開発設計においてドキュメントを書くということ(Markdown、UML)

clo2_

ソフトウェアの開発設計にドキュメント作成の重要性はいたるところで語られていますが、いくつかの現場を経験し、目にするドキュメントは期待した内容でないものが多く、最悪全くドキュメントが残されていないという状態も多々ありました。(😇「ソースコードが正です」😨え)

時間がないこと、度々変わる要件や要望に合わせて対応修正しなければならない等、理由は様々あると思いますが、単純にドキュメント作成がコーディング(プログラミング)に比べて楽しくない(モチベーションが上がらない)からだと私は思っています。

余談ですが、私は可搬性の低く履歴管理のしにくいWord/ExcelフォーマットにMicrosoft特有のお節介機能(オートコレクト等)にイライラしながらドキュメントを作成することに、楽しさや意義を見出すことができません。（客先指定フォーマットがいまだにMicrosoftOfficeフォーマットなのが本当に残念です。）

この課題に対して私が現時点で以下の方法が良いのでないかと考えています。

・Markdown(プレーンテキスト)で文章を構成する
・UML(PlantUML)で図を表記する
・ドキュメント履歴はGitで管理

理由は以下のになります。

・イニシャルコストが低い(Markdown記法は覚えるのが簡単）
・履歴差分管理が容易(Gitのバージョン管理機能に任せる)
　→ソースと同じリポジトリで管理しソース修正と同時にドキュメントも修正できたら理想
・UML図を簡単に手早く書くことができる（PlantUML）
・MicrosoftOffice不要、OS非依存
・書いてて楽しい　←これ大事！


環境設定

私が推奨するドキュメント作成環境は：

・エディタ：　VisualStudioCode（vscode)　(v1.50.1)
・vscode拡張機能(プラグイン)：　Markdown Preview Enhanced （v0.5.13）

これだけです。導入のイニシャルコストも低いですね。
（執筆時のバージョンを示しています）

なぜこの環境を推奨するかを以下に示します。

VisualStudioCode（vscode)は。Microsoftが提供する比較的後発のOSSエディタです。マルチプラットフォーム対応(Win/Mac/Linux)で動作も軽く、単体でもそれなりに機能は揃っています。開発者間でも人気が高く多くの便利な拡張機能（プラグイン）が日々開発されています。（ほぼ同じ仕様のAtomというエディタをかつては使用していましたが、動作が重過ぎて使うのをやめました）

拡張機能Markdown Preview Enhancedは,、vscode単体では表現が乏しいMarkdownに図や数式等を表現するための機能(モジュール)を寄せ集めた、いわゆるおかずたっぷりお弁当パックだと考えています。

画像1

拡張機能インストールはvscodeを起動してExtentions(Ctrl＋Shift＋x)の画面の検索欄で"markdown preview enhanced"と入力し「Install」を押下することでできます。
インストール後はマークダウンテキスト(.md)編集時にCtrl＋K -> V　でMarkdown Preview Enhancedのプレビュー表示が可能です。

画像2

Markdown Preview Enhancedに入っている機能の中でもお気に入り且つお世話になってる機能が特定の記法のプレーンテキストをUML図に変換してくれるPlatUMLです。以下のようにコードブロック(```開始)の部分にpumlかplantumlと書いておくとMarkdown Preview EnhancedがPlantUML記法と解釈してくれます。

本文BBBBBBBBBBBB

```plantuml
私 -> あなた :　ただいま
私 <- あなた :　おかえり
```

画像3

PlantUMLについては以下にまとまったPDF資料がにあります。
http://pdf.plantuml.net/PlantUML_Language_Reference_Guide_ja.pdf
UMLを表示できるは当然のこととして、私の知らない間にマインドマップやガントチャートが表示できるようになっているのには驚きました。

デメリット・懸念点

最初に導入すべき理由やメリットを記載しましたが、ここではデメリットや懸念点を上げます。

■枯れてない
VisualStudioCode（vscode)、Markdown Preview Enhancedともに日々更新されています。以前よりは落ち着いてきましたが、バージョンアップにより、表示できていたものが表示できなくなることがありました。（過去のバージョンを手動でインストールするなどの対処が必要になることがあります）

■対象が大規模過ぎるものには適さない
PlantUMLはテキストからUML図を生成するため、GUIの操作のように細かな配置変更をすることができません。クラス図やアクティビティ図など要素10以上のものを結線して表現しようとするとぐちゃぐちゃになりがちです。また、大き過ぎるUML図等はPDFや印刷時に見切れてしまいます。(※)以上のことから、比較的小さい規模か、上位の抽象化された対象で資料を作る際にはメンテナンスもしやすく有用なドキュメントになると考えますが、1から10まで事細かに記載を求められる巨大な資料づくりには適さないと考えます。（そもそもそういう巨大な資料を私は見る気にはなれません）

※UML図が大き過ぎて見切れる対策としては、「1資料に文と図が混在できる」メリットを放棄することになってしまいますが、UML図は.mdファイルとは別に拡張子 .puのファイルにPlantUMLを記述しSVGやPNG等に出力して印刷する等の対応は可能です。


最後に

思ったよりも長くなってしましました。
開発設計においてドキュメントは必須であると考えますが、令和になった今もドキュメントが全く残っていないことや、体裁フォーマットだけ整えられて中身が全く価値がない（実装と一致していない等）資料をよく見かけます。メンテナンスがされていない死んだ資料ですね。
開発は常に時間に追われていますしバグも出ます。問答無用に要件や仕様の変更も飛んできます。早く対応しろと言われます。そんな中で、資料を残すということはどうしても優先度が低く位置付けられますが、機能の修正や保守する場合には、実装と一致しておりメンテナンスされた「生きたドキュメント」はなくてはならない情報源になります。（長々と書かれた文章よりも図が一番ありがたいですね）そんな生きたドキュメントを残していけるようにするためには、極力無駄なコストをかけずにメンテナンスしていくことが必要になると考えます。私の知っている限りでは、このドキュメント作成補法が一番リーズナブルではないかと考えています。


この記事が気に入ったらサポートをしてみませんか？