概要

以前、業務で設計書を作成する際に行った改善活動をまとめます。
その現場では、設計書をスプレッドシートで作成するという悪習があったため、
設計書をMarkdownで作成するように変更し、gitで管理できるようにしました。
また、その現場の社内用gitlabではplantumlを画像として表示する機能が提供されていなかったため、
jenkinsを使ってplantumlをsvgに変換、Markdownと共に別サーバに転送し、
docsifyというツールでhtmlとして参照しました。

全体の概要図は次の通りです。

説明

①gitへpush

ローカル環境で編集したMarkdownファイルをgitのリモートリポジトリへpushします。

②pushにhook

①のpushイベントにhookさせてjenkinsのjobを起動させます。
webhookはgitlabの各リポジトリーの設定画面から設定可能です。
https://docs.gitlab.com/ee/user/project/integrations/webhooks.html

③md・puファイル取得

jenkinsのjob内でgitリポジトリーからMarkdownファイルと、
図作成用のpu(plantuml)ファイルをチェックアウトします。

④pu→svg変換

puファイルを画像として参照するために、svgファイルに変換します。
jenkinsのslaveサーバにplantuml.jarを配置し、拡張子がpuのファイルに対して変換処理を実施します。
http://plantuml.com/ja/

⑤docsifyへdeploy

docsifyが動作しているサーバへ、Markdownファイルとsvgファイルをdeployします。
ファイルのdeployはjenkinsのsshプラグインをjob内で利用します。
https://wiki.jenkins.io/display/JENKINS/SSH+plugin

docsifyはmdファイルをお手軽にhtmlとして参照できるツールです。
https://docsify.js.org/#/

⑥参照

レビュアはdocsifyにwebサイトとして公開された設計書を参照します。

⑦フィードバック

編集者はレビュアから指摘事項をフィードバックとして受け取り、
設計書の修正を行います。

フィードバックループ

⑦のフィードバックを得た後に設計書を修正し、gitにpushすることで①～⑦の手順をループさせ、
フィードバックループを用いて設計書を改善していきます。

工夫した点

puファイルの格納フォルダ構成

docsifyではplantumlを画像として認識できないため、
プロジェクトのフォルダ構成を次のようにしました。

ページ名(フォルダ)
 └ ページ名.assets(フォルダ)
   └ ignore(フォルダ)
     └ .pu(ファイル)

ページ名.assetsフォルダの直下にはファイルは配置しないままpushしておき、
jenkinsのjob内の処理でignoreフォルダ内のpuファイルをsvgファイルに変換します。
変換したsvgファイルはページ名.assetsフォルダ直下に配置し、
ignoreフォルダはフォルダごと削除します。

jenkinsのjobの処理後は次のようなフォルダ構成になります。

ページ名(フォルダ)
 └ ページ名.assets(フォルダ)
   └ .svg(ファイル)

こうすることでdeploy時に不要なpuファイルを削除し、svgファイルのみが残るようにしました。
Markdownファイルからは上記のフォルダ構成時のsvgファイルを参照します。

この工夫についてはgitlabのplantuml参照機能が使えれば気にする必要はないので、
さほど重要ではありません。

最後に

今回は設計書をMarkdownで書き、plantumlで作図してhtmlとして公開する方法の１例を紹介しました。
概要でも触れましたが、個人的には設計書をエクセルやスプレッドシートで作成するのは、
"バージョン管理"や"別の人が作った図の編集のしにくさ"から考えるとナンセンスだと思っています。

インフラ構成の自動化として"infrastructure as code"という言葉がありますが、
設計書についても同様に"as code"としてgit管理し、修正や参照のしやすい方式を模索していく風潮が
広まれば良いと思います。