概要
以前、業務で設計書を作成する際に行った改善活動をまとめます。
その現場では、設計書をスプレッドシートで作成するという悪習があったため、
設計書を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管理し、修正や参照のしやすい方式を模索していく風潮が
広まれば良いと思います。