GitLab.comとMarkdownで仕様書を書く試み -

GitLab.comとMarkdownで仕様書を書く試み

2018.12.06

こんにちは、コンサルティングサービス本部の朝日です。
システム開発のドキュメントはExcelという現場もまだまだ多いのではないでしょうか。
ややもするとネ申エクセルになりがちですし、個人的にはExcel仕様書嫌いなので、なんとかしたいなーと感じています。

Excel仕様書の一番の問題は、Git等の構成管理システムと相性が悪いことだと思っています。
Gitでファイル自体のバージョン管理はできたとしても、テキストではないので、どこが変更されたかの差分表示が厳しいです。
(しかも大抵の場合はファイルサーバーでファイル名に日付をつけてバージョン管理してたりして…)

そこで、なんとかドキュメント類をMarkdownのようなテキストで記述できないものか考えていました。
ただ、Markdownは表くらいは書けますが、あくまでテキストを書くためのものなので、複雑な図形などは別のツールで作った画像ファイルを載せるくらいしかできません。
Excelではそれなりに図形が書けるので、それもなかなかExcel仕様書がなくならない一因なんでしょう。

個人的には結構前から図形を書く際にGraphvizを使ってテキストから図を起こしていたので、似た方法で図形も文章もテキストで記述してあげることでgit管理できないかと思っていたところ、GitLabでPlantUMLやmermaid.jsをサポートしているという情報があったので、最近社内で利用が増えてきたGitLab.comを前提にどんな感じか紹介したいと思います。

GitLab.com+mermaid.js

GitLab.comでMarkdownを表示する際に、コードブロックの言語に"mermaid"と指定すると、

``` mermaid
sequenceDiagram
    participant Alice
    participant Bob
    Alice->John: Hello John, how are you?
    loop Healthcheck
        John->John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail...
    John-->Alice: Great!
    John->Bob: How about you?
    Bob-->John: Jolly good!
```

下記のような図を表示させることができます。

テキストでノード(AliceやBob)を定義して、そのノード間をエッジ(–>等)で結んであげると、良い感じに図にしてくれます。
詳しいmermaid.jsの記法については、サイトを参照してください。
レイアウト等はツール任せの部分が多いので、細かい体裁にこだわる場合には向いてないと思います。

差分の表示

GitLab.comでテキストで管理できるということは、当然差分についてもわかりやすく表示できます。
下記の図は先ほどのシーケンス図から少しだけ変更しましたが、図の状態だと変更箇所がわかりにくいです。

テキスト差分で確認すると、以下のように変更箇所が明確になります。

わかりやすいですね！

Visual Studio Code + Markdown Preview Enhanced

Markdown+mermaid.jsを記述するためのエディタして、Visual Studio CodeとそのプラグインMarkdown Preview Enhancedを使ってみました。
このプラグインでは、mermaid.jsだけでなく、PlantUML、GraphVizにも対応していますのでついでに紹介します。

mermaid.js

フローチャートやシーケンス図が書けます。

フローチャートサンプル

``` mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

PlantUML

mermaid.jsよりも対応しているUMLの種類が多く、シーケンス図、ユースケース図、クラス図等が書けます。

ユースケース図サンプル

``` plantuml
@startuml
:Main Admin: as Admin
(Use the application) as (Use)

User -> (Start)
User --> (Use)

Admin ---> (Use)

note right of Admin : This is an example.

note right of (Use)
A note can also
be on several lines
end note

note "This note is connected\nto several objects." as N2
(Start) .. N2
N2 .. (Use)
@enduml
```

Graphviz

有向グラフや無向グラフを書くためのツールです。
プラグインだけでは表示できないので、Graphvizサイトからパッケージをダウンロードしてインストールしておく必要があります。

``` dot
digraph finite_state_machine {
    rankdir=LR;
    size="8,5"
    node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
    node [shape = circle];
    LR_0 -> LR_2 [ label = "SS(B)" ];
    LR_0 -> LR_1 [ label = "SS(S)" ];
    LR_1 -> LR_3 [ label = "S($end)" ];
    LR_2 -> LR_6 [ label = "SS(b)" ];
    LR_2 -> LR_5 [ label = "SS(a)" ];
    LR_2 -> LR_4 [ label = "S(A)" ];
    LR_5 -> LR_7 [ label = "S(b)" ];
    LR_5 -> LR_5 [ label = "S(a)" ];
    LR_6 -> LR_6 [ label = "S(b)" ];
    LR_6 -> LR_5 [ label = "S(a)" ];
    LR_7 -> LR_8 [ label = "S(b)" ];
    LR_7 -> LR_5 [ label = "S(a)" ];
    LR_8 -> LR_6 [ label = "S(b)" ];
    LR_8 -> LR_5 [ label = "S(a)" ];
}
```

その他の選択肢

Gitlab CE/EE + PlantUML

残念ながらGitLab.comでは対応していないのですが、GitLab CE/EEではPlantUMLをMarkdown(とAsciiDoc)で表示できるそうです。
別途PlantUMLサーバーを立てる必要がありますが…。
今回はGitLab.com前提としたので、見送りましたが、PlantUMLを使いたい、というときにはこっちを選択するのも良いかもしれません。

GitHub + Chrome拡張(Pegmmatite)

GitLab.comでは対応してませんが、GitHubであれば、Chrome拡張をインストールすることで、PlantUMLを表示できます。

さいごに

まだまだGitLab.comだと対応してなかったりするものが多いですが、次第に対応が増えていってくれることを期待して、できるだけ仕様書をテキストで書いていくようにしていきたいですね。
それでは、今回はこれで。

TOPに戻る

ENGINEER BLOG