こんにちはCTOの馬場です。
このたび納品ドキュメント作成で永らく使っていたWordを卒業し、 Markdownで書いてPDFで納める活動を始めたので公開します。
Wordを使っていると並行編集作業できない、改訂履歴追跡が難しいなどの課題があり、その解決のためにいろいろ模索してこの形になりました。 この仕組みには、こんなイイところがあります。
- Markdownで書ける
- gitで差分管理、版管理される
- GitLab のマージリクエスト(GitHubで言うところのPull Request)を使ってレビュー・リリース管理できる
- GitLab CIで自動ビルドされる
- GitLab CI + Jenkinsで自動デプロイされる
以下のツール群を利用しています。
ワークフロー
GitLab CIを核としてこのようなフローで動いています。
- 各自のPCでMarkdownを書く
- HTMLライブプレビューを見ながら書く&書く
- 適宜commitしたりGitLabにpushしたり
- pushされるとGitLab CIが発動してドキュメントをビルドしHTML・PDFを生成
- マージリクエスト
- マージリクエスト画面でdiffを見て差分を確認
- 変更履歴はマージリクエスト番号を利用
- マージ => ビルド
- ドキュメント内の案件名はGitLabのグループ名を利用し自動付与
- マージされると GitLab CIでビルド => Jenkinsをkick => 最新版HTML・PDFをGoogle Driveにデプロイ
環境まわりのポイントとして大きいのは、 ビルド環境をDocker化した ことです。
ビルド環境をDocker化することで、 手元のビルド環境が不安定になるリスクを排し手間を減らせました。
また手元のビルド結果とサーバでのビルドがずれることがなくなりました。
なぜMkDocs？
ドキュメンテーションの定番といえば Sphinx です。 私個人はSphinxで300ページくらいの本を2冊ほど書いたくらいにはSphinxスキーなのですが、今回は選定しませんでした。
- 全社対象として考えると reStructuredText がどうにも書きづらい
- 他のシステム(GitHub, GitLab, Redmine, Backlogなどなど)もMarkdownで使ってるし、Markdownで書きたい
- つまりMarkdownで書きたい
SphinxのMarkdown化は不可能ではないのですが、 現状あまりきちんと取り組まれている感じではなく、 基本Markdownで一部reStracturedTextみたいなのを書くことになるならばMarkdownに独自に文法を実装したほうがよかろう、、、ということでSphinxはやめました。
そこでメンバーが個人的に検証していたMkDocsを利用することにしました。 シンプルで拡張しやすい、いいツールです。
Markdownの表現力不足の対策
Wordと比べるとMarkdownはどうしても表現力不足です。 そこでMarkdown化に際して表記を見直し、 表をリストに変更するなどの対応を行いました。
しかしどうしても必要な機能があり、そこはもうどうしようもないので独自に実装することにしました。
こうしてできたのが HEARTBEATS Flavored Markdown extension です。
PyPIで公開しているのでどなたでも簡単に利用できます。
pip install hbfm
実装したのは
- 文字色指定
{{color(red)::some_text}}と書くとsome_textが赤文字になる
- 相互参照
## Some Textというタイトル行があるとき、[Some Text](#Some Text)というリンクを作成するときちんとタイトルにリンクする(章番号もつく)
- 表内リスト
- (これはオマケみたいなもの)
です。
直近最大の課題：システム名
ずっとプロジェクト名を決めずにやってきたため、 いまさら呼称が必要になり困っています。
例: 社内ナレッジベース => ナレッジためぞう
真っ先に思いついた「新仕様書システム」というのがありますが、 これだけは絶対にやめようという話になってます。
イイ感じの案があればTwitterなどでぜひ教えて欲しいです。
2017/4/28 Flavored の綴りが一貫して間違ってたので直しました
2017/5/26追記: システム名が決まりました！
社内外の皆様からいただいたご意見を参考にさせていただきシステム名を決定しました！
です！
由来は二宮金次郎です。なんか賢そうだし本を運んでくれそうだし。
今後とも引き続きkinjiroを擁するハートビーツをご愛顧よろしくお願いいたします。
