Through the kaleidscope

プログラミングとかシステム開発とか諸々の思考場所

Markdownで書いた仕様書をWordで納品する方法

受託開発だと発注元に仕様書や設計書などのドキュメントを納品するのが慣習だ。それらのドキュメントはWordかExcelのMSOfficeの作ったフォーマットが暗黙の了解となっている。

Excel方眼紙の仕様書・設計書が嫌で最近はWordで書いているのがこれが扱いにくい。Excelでもそうだがまずバージョン管理がしづらいし、前版との差分がわかりづらい。最近のdiffツールはWordとかの差分も出してくれるようだがテキストベースのものとは確認のしやすさに雲泥の差があると感じる。

Office文書はそういう意味でGitでバージョン管理したとしても差分が確認しづらいのであまりその恩恵を受けにくい。この修正はいったいどういう背景があるのか、仕様を具体的な文章で読みたくても差分だけ判別しにくい。コードを読めばいいが、コードを読み解くよりも文章で読んだほうが効率的だ。ただし、そもそもドキュメントがコードと同期されているほうが稀ではあるのだが。

そしてドキュメントの作成ツールとしてもMSOfficeは扱いにくいと感じる。 Wordは構造とスタイルが密接に絡みついているし、ネストした箇条書きを書こうとするといつもハマる。「2.1.1 見出し3」としたいのに、「2.2 見出し3」とかなっているのをどう直したらいいのか分からない。俺は構造化した文章を書きたいだけなんだ。

Excel方眼紙は自由度は高いのかもしれないが、長い文章を書くときにいちいちちょうどよい長さで切って次行のセルに書くのがめんどくさい。文章を半行くらい加筆するとはみ出た文を次の行に差し込んで、はみ出た文章を切り取ってまた次行に……とどうでもいいことに気を回さなきゃいけなくてめんどくさい。自分が神経質で文章の行末はページの右端からちょうどよい位置までぴったり合わないと気がすまないので、本当にそういうことを感じさせず、純粋に文章の作成だけに集中させて欲しいと願ってしまう。

前置きが長くなった。

様々な理由、合理的な理由、宗教的な理由も含まれるができればMSOfficeは使いたくないので、納品物がある場合(ほとんどそうだが)、そのドキュメント作成は非常に気が重い。

そこで最近、Wordに書くのではなく、Markdownでテキストファイルに書くようにしたら仕様書作成が苦にならなくなった。何より使い慣れたVimで書けるのは編集において大きなアドバンテージだ。VimにはもちろんMarddownシンタックスハイライトを入れているので、マークアップに問題はないし、プラグインを入れてブラウザでプレビューを見ることも出来る。

そして納品するためのWordファイルには、PandocというライブラリでMarkdownから変換してdocxファイルを生成している。ちょっとスタイルがもさいので、予め作っておいたスタイルを後で適用し、表紙や目次はその時に追加しているが、提出のタイミングでするだけなので負担ではない。

Markdownで書いておけば、それをHTMLに変換してサーバにアップすればインターネット越しに見られるし、Wordに変換すればそれを古き良きSI会社に納品できる。mdファイルはテキストなのでGitで差分を見るのも容易い。

図や表などを記述するのが難点ではあるが、参考資料として別ファイル管理すればいいかと思っているので今のところ問題はない。(まあ画面仕様書とかはExcelで作るのがよいと思うが、本来専用のソフトがあってしかるべきだろう。しかしあらゆるドキュメント作成でMSが大勝利したため当分は状況は変わらなさそうだ)

書くのに抵抗がなくなったので、仕様変更があってもドキュメントを更新するのを忘れなくなる……はずだ。