ワークフロー

GitLab CIを核としてこのようなフローで動いています。

1. 各自のPCでMarkdownを書く
   • HTMLライブプレビューを見ながら書く&書く
   • 適宜commitしたりGitLabにpushしたり
   • pushされるとGitLab CIが発動してドキュメントをビルドしHTML・PDFを生成
2. マージリクエスト
   • マージリクエスト画面でdiffを見て差分を確認
   • 変更履歴はマージリクエスト番号を利用
3. マージ => ビルド
   • ドキュメント内の案件名は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を擁するハートビーツをご愛顧よろしくお願いいたします。