gitbookで設計書を作成したら最高だった話
こんにちは。Akerunエンジニアの @ishturk です。
Akerun Advent Calendarの記事です。
今日は設計書の話です。
設計書をどんなツールで書くかは、僕らソフトウェアエンジニアの尽きない悩み（楽しみ）ですね。
最近はまったツールが最高に良かったので紹介させてください。
僕のツールに求める要件は以下です。
- 編集がカジュアルにできる
- UMLが書ける。あとから編集できる（画像での貼付けは編集できないのでNG）
- バージョンの管理ができる
- 好きになれる（重要）
変遷と pros/cons
MS Word
pros
良くも悪くもスタンダードなツールですね。
だれでも編集できるのが強みです。
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でイイ気がしてます。
告知
弊社ではエンジニアを募集しています！
追記
画面遷移などの画像を設計書と一緒に管理する話を投稿しました
