Excelの仕様書を見ながら、プログラミングするのって、なんだか、煩わしいって、思ったことないですか？

Excel方眼紙の仕様書をうんぬん言ってるんじゃなくて、それがWordの仕様書でも嫌なんです。HTMLになった仕様書をブラウザで見るのも嫌。

コーディングしながら、仕様書を見ながら、関連仕様をgrepして確認して、仕様書に間違いを見つけたら即修正して・・・と、こんな感じで、できるだけ、 実装の流れを止めずに仕事する ことってできないものか？
ということで、なるべくテキストエディタだけで仕事できたら良いんじゃない？というお話です。

wikiで仕様書を共有する

弊社の開発では、プロジェクト管理に Redmine、GitHub、GitLab、Backlog などを使ってますが、wikiにプロジェクトの概要や、各種手順、議事録などをまとめるため、マークダウンで文書を書くということが、日常的になっています。
でも、設計書の類は、Excelで執筆して、ファイルサーバーで共有するというやり方が大多数です。やはり、納品物としてマークダウンというのは、うーんって感じですね。

そんな中、先日、あるプロジェクトで、設計書としての納品物の体裁はなんでもよいというお客様がいたので、設計書もwikiで書いてwikiそのものを成果物にする試みを行いました。
そのプロジェクトで使用したのは、GitLabです。
コードの管理だけではなくて、wikiもあるし、課題管理もできて、且つ、プライベートリポジトリが無料というのも、プロジェクトの性質にマッチしてました。

wikiで記述したドキュメントは、以下の通りです。

• システム概要
• システム構成
• 機能一覧
• 画面一覧
• テーブル定義書
• 画面仕様書
• WEB APIインターフェース仕様書

githubやgitlabのwikiは、それ自体を git clone してエディタで書くことができるので、上記の仕様書は、エディタで執筆しています。

実際にやってみた印象は、 wikiだけでも十分に仕様書として成立する！ です。 でも、同時に、課題もいくつか見えました。

良い点

• ドキュメントをgitでバージョン管理できる
  excelファイルもバージョン管理できるけども、バイナリファイルなので、差分比較できない。
  wikiのテキストファイルは、差分比較ができてよい。

• テキストエディタの軽さ
  文書を執筆するときのアプリケーションの起動の軽さは心地よい。

• 検索性に優れている
  grepでテキスト検索できるので、目的のドキュメントをすぐに探せる。

• ドキュメント間のリンク
  ExcelやWordでもリンクが張れるけども、wikiの手軽さには、遠く及ばない。

• ブラウザで直接編集できる
  設計レビューなどでは、wikiを見ながら、指摘事項をその場で直接修正できる。

  レビューの指摘事項を、即、issueとしてメモできるのも、gitlabを使って感じた良い点でした。

• ドキュメントの共有が楽
  git pushで即共有なので、パスワード付きzipに圧縮して、メールで送信という手間がない。

イマイチな点

• マークダウンでテーブルを書くのが辛い
  よくあるexcelのテーブル定義書の様式で、テーブル定義を書いてみたのだけど、マークダウンでテーブルを書くのが、なにしろ辛い。

• 図が書けない
  テキストだけなので、表現力が乏しい。ちょっとした図を添えたいときに困る。

• 目次も手書き
  Wordなどは、目次を作ってくれるけれど、wikiは、自分で目次を書くしかない。

• 章番号があった方が読みやすい
  MDの場合は、章番号を書かないことが普通なのだけど、長いページでは、章番号があった方が読みやすい（かもしれない）。

  章番号がついた設計書を見慣れているということもあるとは思うのだけど。

• リンク切れ
  手軽にリンクが張れるのはメリットなのだけど、リンク切れすることもよくある。

• 生産性は変わらない
  テキストファイルで仕様書を書いたからといって、設計書の生産性があがるわけではない。

• 成果物としての体裁の弱さ
  このプロジェクトでは、成果物をwikiのままでよかったのだけど、他のプロジェクトでも、このやり方を展開するには、せめて PDF にするくらいのことはできないと厳しい。

a5doc というツールを作りました

やはり、妥協のない文書を書くということにかけては、WordやExcelの方が優れています。
マークダウンは表現力を妥協することで得られるメリットを優先しているわけですが、そのメリットは、お客様のメリットというよりは、プログラミング好きなエンジニアのメリットのように思います。
でも、この内向きなメリットを生産性に結び付けられると、お客様にとってのメリットにもなります。

軽快なテキストエディタのメリットをそのままに、イマイチだった点を改善することができないだろうか・・・と、取り組み始めのが、補助ツール a5doc の開発です。

a5docは、仕様書を書いて保存したら、コミット前に実行して、チェックや自動補正、あるいは自動生成を行います。
例えば、プログラムの開発では、コミット前に lint 等を実行して、コーディングルールのチェックをしますが、そういった感じのことを設計書の執筆過程でもやってみようというわけです。

このツールは、特定のエディタのプラグインとして作ったのではなくて、nodejs で実行するプログラムにしました。 npmで公開してますので参照してみてください。

たった今、実装されている機能を少し説明します。

• 目次の作成
  githubとgitlabのwikiでは、_Sidebar.md を作成してコミットしておくと、右上に目次を表示することができるので、_Sidebar.md を自動生成します。
  目次が自動更新されない問題点は、緩和されると思います。

• テーブル定義の作成
  マークダウンのテーブルを書くのが辛いので、ymlファイルでテーブルの仕様を書いて、MDに変換します。

• ER図の作成
  ymlでテーブルの仕様が明確になっているので、ER図を自動生成できるようになってます。
  ER図は、PlantUMLで出力されます。

• swagger.ymlからAPI仕様書を作成
  APIもテーブル定義の方式と同じく、ymlを書いてMDに変換します。
  そして、APIのymlなら、わざわざ独自仕様を作成するまでもありません。swagger.ymlを書いて、MDに変換します。
  swagger.ymlなら、実装フェーズでも、有効活用できます。

・・・・

まだ実装された機能は少ないですが、これから追加していきたいと思っている機能は、ドキュメントの中から用語を自動的に抽出して用語集を自動生成したり、用語の揺れチェックをしたり、あるいは、自動的にリンクを張り込んだり・・・とか、そんなことを考えています。
こういうのは、ExcelやWordのドキュメントでは難しいけども、wikiで仕様書を書いてれば可能なことだったりします。
設計書の品質が高まることとか、設計工程の生産性が向上しそうなことを目的として、機能開発に取り組んでいきます。

a5docで作成された設計書は、単なるテキストファイルなので、a5docが無くなっても、設計書のメンテナンスができます。 捨てることも容易なツール ですので、一度、お試しください。

ちなみに、テーブル定義やAPIの仕様をymlで書くことによって、プログラムの一部分をひな形出力することもできそうです。
まぁ、今どきのフレームワークは、それ自身の中に、scaffold機能があるので、a5docは、そのscaffold機能を実行するコマンドラインのパラメータを自動生成するとかですかね。
ドキュメントだけじゃなくて、開発のサポートもできるツールにしていきたいなぁと思ってます。

テキストエディタで仕様書を書きたい

テキストエディタで仕様書を書きたい欲が抑えられなくて困ってる人いませんか？
プログラミングが好きな人たちの中には、何人か居るんじゃないでしょうか。
そんな人たちの目に留まるといいなぁ・・・。
きっと、同じような感性を持っている人だと思うので、いっしょに仕事してみたいですね。