価値のあるドキュメント

アジャイル開発手法（※1）が現場に取り入れられるようになって久しくなり、既に採用済みあるいは、採用するべくまい進されている読者の方もいらっしゃると思います。ご存知のとおり、アジャイル開発手法にはその考え方の根幹を成す「アジャイルソフトウェア開発宣言（アジャイルマニフェスト）」があります。その一節に「包括的なドキュメントよりも動くソフトウェアを価値とする」とあるとおり、動くソフトウェアに注力する価値基準ですが、ドキュメントに価値がないといっているわけではありません。今回は、このドキュメントについて、プラクティスを交えながら話をしようと思います。

ウォーターフォール手法を採用した開発現場（プロジェクト）では、あらゆるフェーズでドキュメントを作成します。上流工程の成果物である業務フローや要件定義書をはじめ、下流工程の成果物である外部（基本）／内部（詳細）設計書やテスト計画書まで、目的や内容は多岐に渡ります。フェーズごとの品質や進捗状況を評価するためには必須なものであり、これが包括的なドキュメントです。 一方で、動くソフトウェア＝プロダクトに必要なドキュメントは何かと考えると、その目的は少し異なってきます。究極的に言えば、「何を実現するものなのか」と「どのように振舞うものなのか」の2点に集約されます。前者は要求を整理したものであり、後者は仕様を取りまとめたものになります。

両手法を比較すると違いが見えてきます。どのように実現するのか、つまり"HowTo"のドキュメントの有無です。 これは動くソフトウェアを欲するビジネスサイドから考えると至極当然で、どのように動いているかよりも、何（"What"）を実現できるかどうかに関心があるためと言えます。言い換えると、これらの"What"のドキュメントは価値があるということです。

代表的なものとして、概念モデルやシステムアーキテクチャなどが、"What"のドキュメントとして挙げられます。ちなみに、"HowTo"ドキュメントが一切不要というわけではなく、説明責任を果たす上で必要なドキュメントは中間成果物として作るべきです。案件や顧客属性によって、作成するドキュメントの種類やボリュームを変えていく必要があります。

Model as Code - コードでUMLモデルを書く

さて、皆様はドキュメントを、どのようなツールを使って作成していらっしゃいますか。MS WordやExcelが多いでしょうか。もちろんこれも1つの解だと思います。アジャイル開発の中では、Wikiに書くというのも選択肢の1つです。チーム内で共有することを考えると、Wikiは非常に便利です。本コラムでは、さらに「コードで表現する」ことを提案します。

参画している案件では、AsciiDoc（※2）とPlantUML（※3）というツールを利用してドキュメントを作成しています。AsciiDocは軽量なマークアップのひとつで、あらかじめ定義された構造表現を利用して文書を作成することができます。PlantUMLは独自のDSL（ドメイン特化言語）を利用してUML図を作成することができます。いずれも共通点はテキストであることで、以下の点で優れています。

●バイナリと比較して軽量、かつ差分の比較が可能
●バージョン管理することでチームでの共同開発が容易
●レイアウトは自動で行われるので開発者毎の表記ブレが少ない
●ツールを組合せてリアルタイムで編集可能

専用ツールと比較して表現力が劣るなどの欠点(短所)もありますが、それを補って余りあると思います。どうしても表現できない場合は、別途画像を用意するなどして対処します。 その他、利用しているツール群は下記の通りです。

ドキュメントのための開発ツール群

上記構成では、Visual Studio Codeで編集したものが即座にプレビューされ、確認しながら作業可能なのでスピーディかつ効率的にドキュメント作業を進めることができます。

リアルタイムプレビューでドキュメントを作る

常に共有することをセットで考える

ドキュメントは一度作って終わりではありません。ビジネスの変化に伴いシステムが変化していくように、ドキュメントも日々更新されるものです。特に"What"のドキュメントはそれが顕著です。情報共有がうまくできていない現場では、思い込みや誤解が錯綜し、結果的にシステムの品質にまで影響します。

Wikiでドキュメントを作成する利点の1つに、チーム内での共有しやすさが挙げられます。同じ時間に同じ情報にアクセスしていることを、仕組みとして担保できます。前項でご紹介したツール構成では、作成したドキュメントをHTMLへ変換・出力することができます。これをCIツールに組み込んでWebサーバーへ配置すれば、同様の効果を期待できます。AWSをはじめとしたパブリッククラウドサービスを利用すれば、自前でサーバーを管理せずに（＝サーバーレス）、ドキュメントCIを実現することが可能です。以前のコラムでご紹介したOSS、RedPenと組合せればさらに強力な環境を手に入れることができます。参画している案件では、AWS CodeBuild + Amazon S3(Webホスティング）を利用しています。

まとめ

アジャイル開発手法を採用したからといって、ドキュメントが無くなることはありません。むしろ、その重要性はさらに増すばかりです。作ったきりで形骸化させないためにも、自動化やメンバーの負荷を軽減する施策を導入し、ソフトウェアと同様に環境変化に合わせてドキュメントを進化させていくことができれば、その真価を以ってチーム開発に寄与することでしょう。

• ※1 ここではスクラムを代表とする、いくつかのプラクティスを総称してアジャイル開発手法としています
• ※2 http://asciidoc.org/
• ※3 http://plantuml.com/
• 　
• 本文中に記載されている製品名などは、各社の登録商標または商標です