gitbookで設計書を作成したら最高だった話

こんにちは。Akerunエンジニアの @ishturk です。

Akerun Advent Calendarの記事です。

今日は設計書の話です。

設計書をどんなツールで書くかは、僕らソフトウェアエンジニアの尽きない悩み（楽しみ）ですね。

最近はまったツールが最高に良かったので紹介させてください。

僕のツールに求める要件は以下です。

• 編集がカジュアルにできる
• UMLが書ける。あとから編集できる（画像での貼付けは編集できないのでNG）
• バージョンの管理ができる
• 好きになれる（重要）

変遷と pros/cons

MS Word

pros

良くも悪くもスタンダードなツールですね。

だれでも編集できるのが強みです。

Visioと組み合わせれば、UMLも後から編集可能です

cons

Visioは標準にするには少々値が張ります。

バイナリ形式なのでバージョン管理はしづらいです。

ページが増えたり画像を貼ったりすると重くなって詰みます。

sphinx

pros

テキストベースなのでバージョン管理しやすいです

マークダウンで書けるのもいいです

色々な記法が用意されているので、巨大な設計書も頑張ればスマートに書けます

plantumlとの親和性が高いです

ちゃんとメンテされている

cons

（主観ですが）カジュアルさがちょっと足りない感じ（ごめんなさい）

Google Docs

pros

Wordライクに編集できるので学習コストが低いです

UMLを扱うにはplantuml gizmoのプラグインがgoodです

クラウドなので同時編集ができるのもいいです

バージョン管理は独自機能で（一応）できます

cons

外部サービスなのでそもそも許可してもらえないことが多いですね

こちらも、ページが増えたり画像を貼ったりすると重くなって詰みます

gitbook

pros

テキストベースなのでバージョン管理しやすいです

マークダウンで書けます

plantumlとの親和性が高いです。他のpluginも豊富です

gitとの親和性が高い（gitbookだし）のもいいです

カジュアルさがちょうどいい。僕的にはココがツボ

cons

今のところ不満がないです

gitbook å°Žå…¥

gitbook とは

• Markdown で書かれたドキュメントをツリー形式のhtml文書に変換するツールセット
• ビルド、サーバー機能を持つ
• ツリーの作り方がシンプル （対 sphinx 比
• プラグインに対応
• node で動く

å°Žå…¥

nvm + node をいれる

node のバージョンは v5.12 推奨(v6系でも動くらしい)

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.2/install.sh | bash
nvm install v5.12
nvm use v5.12

gitbook å°Žå…¥

npm でinstall します。 npm自体のinstallは省略

npm install -g gitbook-cli

ドキュメントのビルド

tree 構造

.
├── README.md
├── SUMMARY.md
├── book.json
├── docs
└── node_modules

• README.md : トップページになります。
• SUMMARY.md : ドキュメントツリーを記載するファイル
• book.json : 設定ファイル。pluginもココに書く
• docs : ユーザーファイルを追加するディレクトリ（SUMMARY.mdで自由に決めてね）
• node_modules : nodeですから

README.md を設定しておくと、githubでみても、READMEとして表示されるので、一元管理できるのもいいです。

ビルド

ディレクトリのルートでビルドします。デフォルトはhtmlです。pdfとかも吐けます。

gitbook build

ファイルの追加

この例では、docs/下に文書を作成、配置します。

SUMMARY.md の例。ネストできます。

1 # SUMMARY
2
3 * [概要設計](docs/README.md)
4   * [ほげらの章](docs/hogera.md)

plugin の追加

plugin の導入自体はnpmで。（ちゃんとやるならbuildした時に不足しているpluginをinstallするようにしてね）

たとえばplantumlだと、

npm install gitbook-plugin-uml

導入したら使用するpluginを、book.json に記載します

 1 {
 2     "plugins": ["uml","-search"],
 3     "pluginsConfig": {
 4         "uml": {
 5             "format": "svg",
 6             "charset" : "UTF-8",
 7             "nailgun": false
 8         }
 9     }
10 }

ドキュメントの配信

ローカルので実行

gitbook serve

とすると、webサーバーになってブラウザで閲覧できるようになります

デモ

Jenkins + git (github) webhook

gitのコミットでwebhookを引っ掛けてファイルを取得すればドキュメントの自動更新を設定できます。

Jenkinsが導入されているサーバーにgitbookも導入してあげれば、簡単に設定できますね。

gitbookのserver機能を使えば、自前のwebサーバーも不要です。

簡単にチームで設計書を共有できて、最高でした。

おわりに

また新しいものが出たらいろいろ試したいですが、しばらくはgitbookでイイ気がしてます。

告知

弊社ではエンジニアを募集しています！

www.wantedly.com

追記

画面遷移などの画像を設計書と一緒に管理する話を投稿しました

akerun.hateblo.jp