忙しい方へ
おそらく、大抵のソフトウェアの仕様書はExcelで管理することが多いと思います。しかし、バージョン管理や差分がGitHubと比べてイマイチだと思っていました。
そのような問題を解決するために、まずは（個人的に）取り組みやすいテスト仕様書をMarkdown+GitHubで管理するという試みをしてみました。バージョン管理や差分管理は確かにやりやすくなりました。ついでに、一覧で眺めたり集計したいときに変換するpythonスクリプトも作成しました。
変換ソースコードは GitHub で公開しています。
不要なExcelを撲滅したい
未だにソフトウェアの仕様書にExcelを管理する場合が多いと思います。私はこのExcel管理に嫌気がさしていました。
- バイナリデータのため、GitHubなどのバージョン管理ツールとの相性が悪い。"〇〇_最終版.xlsx", "〇〇_最終版_new.xlsx", "〇〇_最終版（これを使う）.xlsx"のようなファイルが同一ディレクトリ内にあると禿げそうになります。
- 誰がいつどのように編集したのか、という差分管理もイマイチ。
- ファイルが大きくなると、オープンや保存にも異様に時間がかかる。
- そもそも仕様書がどこにあるかが、誰かに聞かないとわからない
等、挙げればキリがありません。ソースコードはGitHubで管理しているのだから、同じ場所・同じツールで仕様書を統一管理したいという思いが強くなっていきました。
とはいってもいきなり全部を置き換えるのは難しいため、まずは個人的に取り組みやすかったテスト仕様書Excelの撲滅に取り組みました。
Markdown+GitHubによるテスト仕様書管理
Markdown+GitHubならば上記の悩みをほぼ解決してくれましたが、Markdownはテキストベースのため、一覧表示ができなかったり、集計作業はできませんでした。そこで、Markdown型テスト仕様書をExcelに変換するpythonスクリプトを作成しました。ソースコードは GitHub で公開しています。
実際に使ってみて
実際のプロジェクトで運用してみて、良い点もあれば課題も見えてきました。
良かった点
- ソースコードと同じディレクトリ階層で仕様書を管理できるため、仕様書を探す手間が省けた。
- 仕様書内まで一括検索・置換ができるようになった（Excelは開くまで中身がわからなかった）。
- バージョン管理や差分管理がものすごく快適になった。
- オープンにもほとんど時間がかからず、生産性が向上した。
- IDEだけで作業が完結するようになった。IDE/エディタとExcelのにらめっこ作業がなくなった。
課題
- 図表現が弱い。テスト結果のスクリーンショットの貼り付けができない。
- 集計作業ができない。ここはさすがにExcelに軍配。
さいごに
Markdownによる仕様書管理はまだまだ発展途上ではありますが、正直従来のExcel管理よりかは恩恵が大きいと感じました。旧式の方法を一新するのは中々骨が折れますが、できる範囲で続けていこうと思いました。次はもっと別の仕様書で。