1. 前説：こんな書かれ方をするといやなのだ
みなさん、ソフトウェアの設計書ってどうやって書いてます？
....やっぱExcelですよね、この業界。
僕の周囲でもこれはそうなんだけど、個人的には
- 自分一人で設計を書き、
- その設計をもとに自分一人で実装し、
- 実装内容とは無関係な体裁の修正に、十分な時間がかけられ、
- 版の管理は気にしなくてよい
場合になら、たぶんExcelを普通に使うと思う。
ただ、実際の現場だとそんな悠長なことを言っていられるわけでもなく、人が書いた設計書をもとに実装、なんてことは普通で、場合によってはこんな設計書()に出くわすこともありうる。
この場合の正解は、商品情報.商品カテゴリが104のとき、商品情報.個数を加算する。なんだけど、不要な情報が一緒に目に飛び込んでくるのは、正直勘弁してほしいと思う。個人的には。
それに、設計書がMicrosoft Office(xlsだと特に)だとこんなことが起きうる。
- 共有ディスクに設計書がアップされる
- 共有ディスクの設計書ファイルをそのまま開くと、反応が悪い上に場合によってはファイルを破壊する可能性もあるので、作業効率を優先してローカルディスクにダウンロード
- 実装作業中の設計書がいつの間にか更新される（アナウンスはなし）
- 更新を知らないままローカルファイルで実装を終える
- 「設計と挙動が違う」とバグ表を切られる
ほかにもいろいろあるが、設計書がMicrosoft Officeだとこんな弊害が起きる、と個人的には考えている。
- 版の管理にはOneDrive for Businessとかが必要で、ふつうのVCSでやるのは悪夢でしかない
- （上に関連するが）リビジョン間で「どこがどう変わったか」を把握するのは、容易なことではないので、一つの最終版ドキュメントにすべての情報を押し込めようとする
- 集中管理されるべき設計書がカジュアルコピーとして拡散するので、どれが本物かわからなくなる
- 設計とは本質的に関係のない「体裁の修正」に、少なくはない労力を割かなければならない
ここまでで終わらせたらただの文句でしかないので、どうすればましになるかを考える。
2. 設計書作成ツールとしてのMicrosoft Office
オフィススイートであるMicrosoft Officeでもっとも設計書作成で使われるのは、表計算ソフトであるExcelじゃないだろうか。
表計算をほとんど必要としない文書なのに、なぜExcelを使うのか、僕なりに考察してみた。
- 日本には昔から「方眼紙文化」があるが、Wordだと方眼紙的なインデントが面倒だが、Excelだとセルを狭めることで方眼紙的なレイアウトを容易に再現できる
- 複数の独立した文書を、「ワークシート」という単位で一つのファイルにまとめることができる
- 日本のオフィスPCには、原則Microsoft Officeが入っているので、環境を選ばない。これは、設計書を「納品」しても、それを相手先でも読むことができることを意味する
Excelを使うときの利点を考えたら、僕ではこれくらいしか思いつかない。読者諸兄で、これ以外の利点がご存知ならご教示いただきたい。
個人的には、これらは何もExcelでなくても達成できるものだと思う。
そう考える理由は以下のとおり。
- 方眼紙的なインデントが必要なのは、「一見して文書の意味付けを把握できるようにしたい」という要求の現れなので、要件に合うような文書構造にすればよい
- 独立した文書を一つのファイルにまとめたいなら、HTMLでもできる
- 環境を選ばないファイル形式には、Adobe PDFというものがある
- 版の管理とリビジョン間の更新差分の管理がMicrosoft Officeだと難しいのは、ファイルフォーマットがバイナリが基本なのが原因なので、原稿をプレーンテキストで記述できれば差分管理はVCSが良しなにしてくれる
- 単一の原稿から複数のフォーマットの成果物を生成できれば、「開発時は開発サーバ上のHTMLを参照」し、「納品にはPDFを使う（必要であれば印刷してもよい）」という方式がとれる
- ドキュメントビルダを経由すれば、規定のマークアップ仕様のもとで、体裁は統一された仕様として構造化された文書に紐づくので、「文書体裁の修正」と「ソフトウェアの設計」を明示的に分離できる
前置きが長くなったが、これらを一度に解決する（と僕が考える）ソフトウェアがある。Sphinxである。
3. 本題：ぼくのかんがえたさいきょうのドキュメントCIかんきょう
まずは目標とすることを挙げてみる。
- 文書の意味付けは標準テンプレートでまかなう
- 版の管理をVCSに分離する
- VCSにコミットされた原稿からのビルドは、人手を介することなく自動的に行われるようにする
- 開発中の設計書が拡散しないよう、Webサーバで参照できるようにする
- 納品用成果物となる設計書は、PDFにして管理する
いろいろ挙げたが、概念的にはこんな図になる。
というわけで、ひとつひとつ書いていく。
3-1. プロジェクトとVCSの設定
プロジェクトについては、プロジェクトを作るの記事に従って sphinx-quickstart
を実行して作るだけなので、特に難しいことはないはず。
VCSも、現状Git以上にベターな選択肢はないので、Gitを選択し、外部のホスティングサービスにおいている。ここでは、プライベート／パブリックの切り替えが簡単なAtlassian BitBucketを使っている。
プロジェクトを作ったら、UTF-8を扱えるエディタでreStructuredTextのマークアップ仕様に基づいて設計書を書いていこう。入門記事もある。
3-2. 面倒なことは有能な執事に任せる
「体裁の修正」や「可読性の高い文書ファイルの生成と配置」といった、本質的に設計と関係ないところで労力を割きたくないので、このテの作業はすべてJenkinsに任せる。
BitBucketがプッシュを受け付けたことをトリガーにしてビルドを始めるのが、反映タイミングとしては最速なのだが、これを実現するためにBitBucketにWebHookを設定する。
まず、Jenkins側にBitBucketからのWebHookを受け付けるためのプラグインを導入する。これにはBitBucket pluginを使った。導入自体は、Jenkinsのプラグインマネージャーから行える。
導入したら、ビルドプロジェクトをつくる。
ソースコード管理はGitにする。BitBucketの仕様に従っていれば特に問題はないはず。
次のビルドトリガは Build when a change is pushed to BitBucket
を選択する。
最後に実際のジョブだが、 make
の成果物をディレクトリにコピーするシェルスクリプトを実行する。
Ubuntu の DocumentRoot である /var/www/html 以下に反映する。
#!/bin/bash
HTML_ROOTDIR=/var/www/html/designdoc
UID_TOMCAT=tomcat
UID_WWW=www-data
LANG_CD=ja
HTML_DIST=$HTML_ROOTDIR/$LANG_CD
EPUB_DIST=$HTML_ROOTDIR/epub/$LANG_CD
PDF_DIST=$HTML_ROOTDIR/pdf/$LANG_CD
make clean html epub latexpdf
PS4='+ [${BASH_SOURCE}:${LINENO}] ${FUNCNAME:+$FUNCNAME(): }'
set -vx
if [ ! -e $HTML_ROOTDIR ]; then
mkdir $HTML_ROOTDIR
fi
sudo chown -R $UID_TOMCAT:$UID_TOMCAT $HTML_ROOTDIR
if [ ! -e $HTML_DIST ]; then
mkdir -p $HTML_DIST
fi
rsync -rlDH --delete _build/html $HTML_DIST
if [ ! -e $EPUB_DIST ]; then
mkdir -p $EPUB_DIST
fi
cp -f _build/epub/MySkill.epub $EPUB_DIST
if [ ! -e $PDF_DIST ]; then
mkdir -p $PDF_DIST
fi
cp -f _build/latex/MySkill.pdf $PDF_DIST
sudo chown -R $UID_WWW $HTML_ROOTDIR
set +vx
ただ、 Tomcat の実行ユーザーと Apache の実行ユーザーが違うので、 /etc/sudoers をいじって chown を認証なしで実行できるようにしている。
tomcat ALL=(ALL:ALL) NOPASSWD: /bin/chown
このあたり、もっとましなやりようがないものか。我ながらかなりの力技だ（汗）。
Jenkins側の受け入れ態勢ができたところで、BitBucketのプロジェクトにWebHookを送る設定を書く。
[送信先URL]/bitbucket-hook/
を宛先にする。
ここまでやれば、手元で原稿を書き、それをBitBucketへプッシュするだけで、実装者にも納品担当者にもうれしい設計文書が作られているはずである。
最近のコメント