費用対効果の高いレビューを模索する(レビューしやすいドキュメントに変えていく編)

前回は、ナレッジの共有について仕掛けたことを書いてみました。あれからナレッジマネジメントが気になって気になって。マイケル・ポランニーでも読んでみようかと思い始めております。

mao-instantlife.hatenablog.com

さて、今回は別名「Pandocに夢を見る編」。久しぶりにチームでの施策ではなく(いずれ展開するけど)、その前段階として個人で試してみたことです。味見楽しいです。

世の中には「ドキュメントなんてなくても良い」という極端な人もいますが、自然言語や図や表の方が理解しやすいものも当然あるので、なにがしかのドキュメント(公式、非公式を問わず)は開発には不可避であると思います。また納品物として、契約書に書いてある場合もありますね。それ自体は問題なくて、必要なものは必要なだけ作れば良いんです。それが保守のためであれ契約のためであれ。何が問題かというと低レビューアビリティーの代表とも言えるにっくきExcel方眼紙が跋扈している領域であるというその一点に集約されるわけであります。

これは、レビューのしやすさという観点から脱Excel方眼紙しましょう、というエントリです。

Excel方眼紙使っててつらい所

課題を解決するために敵を知りましょう。Excel方眼紙をレビューすることがどれだけつらいか整理してみます。整理することで心の傷のかさぶたをはがしてしまいそうですが、気にせずいきます。

Excel方眼紙使っててつらい所となると、こんな所ですかね？(個人差はあります)

• 差分に関する情報整理が人力で赤字+打ち消し線とか
• レビュー後の差分表記の人力マージでミスってつらい
• コミットログで差分が取りづらいので変更記録が結局Excelに埋め込まれる
• プルリクでレビュー記録を残しづらい

色々と理由は出てきますが、根本をたどると「ドキュメントがテキストファイルで表現されていない」ことに集約されそうです。方向性がちょっと見えてきました。

テキストじゃないとプルリクエストの利便性に乗っかりづらい

何故、テキストファイルで表現できないと問題なのかというと、プルリクエストの利便性に乗っかれないんですね。私のチームではGithubEnterpriseとTFSを使っていますが*1、コードのレビューはほぼプルリクエストを中心に回っていて、メンバーもこの仕組みには非常にメリットを感じています。プルリクエストを使いたいからTFSで管理しているプロダクトのバージョン管理をTFS標準からGitに切り替えたくらいですし。

で、レビューの記録という観点からすると、プルリクエストはすごく便利なんですよね。レビュー対象ファイルをリストアップしてくれるし、その対象の変更差分も出してくれるし、レビューの指摘も対象箇所に直接コメントを入れることができるし、プルリクエスト全体へのコメントもできる、マージもコンフリクトしてなければ自動でできる。しかも、クローズしたものも記録が残るので、いつレビューをしたのか、指摘の対応が完了したのがいつか、などの記録も正確です。レビュー記録表で人力でやっていたことをシステムで拾ってくれているわけですね。

このプルリクエストという仕組みがコードレビューでうまくまわるのは、対象がテキストファイルだから、ということでしょう。Excelなどのバイナリファイルはやはりこの仕組みに乗っかりづらく、バージョン管理に乗せていてもうまく利便性が得られないということになります。

何故、Excel方眼紙が必要か？

にも関わらず、世の中ではExcel方眼紙が必要とされております(？)。だいたいにおいてそれは「ExcelとWordくらい入ってるから」という消極的な理由であることがほとんどで、だったらテキストエディタくらい入っているだろう、と突っ込みを入れたくなる所ではあるのですが、ExcelやWordで見栄えよく開けること、というのが納品先の心象的にも良かったりするわけです。いざとなれば納品されたドキュメントを誰でも修正できる、とか思っているのでしょう。

ただし、納品先でドキュメントを修正するケースはほとんどありません。となると、見栄えの良いドキュメントが生成できれば良いだけで、原本はテキストファイルでも良い気がします。

ドキュメントのテキストファイル化、理想

ドキュメントもプルリクでレビュー記録を残したい、でも納品時には見栄えくらいは整えたい、を目標にドキュメントのテキスト化に使えるツール探しをしてみたいと思います。

まず、ドキュメントの記載フォーマットについて。テキストファイルとして書けることが大前提ですが、見栄えもある程度保証されないと逆に理解しづらいものになってしまいます。その観点で、ドキュメントの記載フォーマットについては今の所Markdown一択です。GithubのWikiもMarkdownで書けますし、シンタックスがそこそこシンプルです。Github内で表示する場合に見栄えも整えてくれます。

もう一つ、小さいことですが考慮しないと行けないのは、プルリクエストを使いたいので、プロジェクトのWikiではなくリポジトリ内にドキュメントを含めるということですね。下記の通り、Wikiはプルリクエストを送ることができません。(gitでクローンはできるのに。。。)

stackoverflow.com

上記を理想に、Markdownファイルをドキュメントに変換してくれるものを探してみました。

Pandocを使う

PandocはHaskel製のドキュメント変換ツールです。まあ、考えることはみんな同じなはずなので、誰かきた道を遠慮なく進みます。まず公式ドキュメントを見て、多彩な入力形式と出力形式への対応に驚かされましょう。

Pandoc - About pandoc

インストール

ダウンロードページでGithubの最新のリリースタグに飛ばされるわけですが、ダウンロードできるファイルがソースしかないんですね。味見をしたいのはPandocであって、今回はビルド環境作るとか時間をかけたくないので、おとなしくバイナリパッケージが用意されているリリースからダウンロードします。親切にも各環境用のインストーラが用意されているので、私のチームのようにMacが私一人だけ後はWindowsみたいなチーム環境でも特に困ることなく導入できそうです。

素で使ってみる

Pandocの素晴らしい所は、有志の方々による日本語ドキュメントが充実している所です。メンバーにも広めやすいですね。

Pandoc ユーザーズガイド 日本語版 - Japanese Pandoc User's Association

一番シンプルな使い方は、デフォルトのテンプレートを使ったWordへの出力です。適当にマークダウンで書かれたファイルを用意して以下のコマンドを叩いてみます。

pandoc -o hoge.docx input.md

出力されたWordファイルを見ると、各見出しレベルも対応していますし、そのままでもドキュメントとしての見栄えはかなりまとまっています。リンクで指定した画像も問題なく差し込まれます。テンプレートに使われるファイルのスタイルが調整できれば、問題ないレベルです。

複数ファイルのとりまとめ

長いテキストファイルは読むのつらいし、コードと同じく、ドキュメントも構造によって分割したいですよね？ただ、そうすると納品ドキュメントとしては分割されすぎて面倒、というニーズにもPandocは答えてくれます。パラメータの入力となるファイルを複数指定するだけです。入力ファイル同士を空白行で連結した上で出力してくれます。

これで、章立てごとにファイルを分割したり、把握しやすい単位でのドキュメントの分割が可能となります。

書式を指定したテンプレートで使ってみる

デフォルトのテンプレートでも見た目としては十分なレベルだと思いますが、ドキュメントのスタイルが指定されている、というケースもあると思います。もちろんそういうニーズにもPandocは対応しています。書式を変更したファイルをテンプレートにしてドキュメントを作ってみるために、オプション--data-dirと--reference-docxを使ってみます。

pandoc --data-dir=テンプレート保存先ディレクトリ --reference-docx=テンプレートファイル名 -o hoge.docx input.md

上記だと上手く行きませんでしたorz

試行錯誤してみた結果、上手く行ったのは以下のように実行した場合です。

pandoc --reference-docx=テンプレートファイル名のフルパス -o hoge.docx input.md

どうも、data-dirオプションが上手く機能していないようです。また、reference-docxも~/Documentなどの省略形のパスだとファイルを探せず、フルパスでないと機能しませんでした。これがIssueなどで上がっている既知の問題かどうかは把握しておらず、多少面倒ですが、納品のたびに決まったサーバで流すような運用を想定しておけば、あまり大きな問題にはならない気がします。

Graphvizを使う

ここまで来ると、ドキュメントだけでなく他の物もどれだけテキストファイル化できるのだろうかと探ってみたくなります。人間とは欲深い物です。

探してみるとGraphvizという遷移図のようなものをテキストから生成してくれるツールがありました。

http://www.graphviz.org/

d.hatena.ne.jp

私も自分のプロダクトを参考に書いてみましたが、特にスタイルを細かく指定しなくても中々奇麗な図がかけます。が、記法の問題もあり、やはり図で参照できる方が理解度が速いので、生成元として使ってリポジトリに残すのは良いかと思いますが、レビュー対象とするにはあまり向いてない気がします。

これから

出来上がった物については、出力したWordのファイルをメンバーに見せたり、Githubの別ブランチにあげたりしながらメンバーの反応を見てみたのですが、おおむね好評でした。ただし、実際に運用にのせる時に少し整理した方が良いよね、となったところがいくつかあります。

• Graphvizの使いどころが難しい
• 表形式で管理した方が楽なものに対するアプローチ(マクロでDDL吐くテーブル定義書とか)
• Markdownの記述ルール
• 納品ドキュメントに生成するためのスクリプト(Win, linux両方)
• 変更履歴を自動生成したい(Gitのログでなんとかならないか)

ちなみに、テーブル定義書については、メンバーのスキル的にDDLを直接見た方がわかりやすいということもあり、テーブル定義書は納品用にDDLから生成できれば良いのではないか、という意見も。ただし、マイグレーション用のスクリプト管理があるので、情報としてどこまで整理するかは議論してみないと何とも言えないです。

まとめ

運用までは持っていけませんでしたが、方向性としては間違ってなさそうです。プルリクエストの仕組みに乗っかれることで、ドキュメントもソースも同じようなレビュープロセスになるというのは、メリットに感じてくれたみたいでした。まずは、私のナレッジとしてまとめて、運用を目指していきたいと思います。

*1:プロダクトに使う言語によって変えています