(Photo by：Dominique)
アジャイルなソフトウェア開発では、動作するソフトウェアを優先してドキュメントが後回しになりがちです。アジャイルの解釈の仕方になりますが、必要最低限のドキュメントを状況に応じて書くのがアジャイルの基本的な考え方になります。
ここでは、どのようにドキュメントを最小限に抑えるのかを考えて行きます。
利用者と利用シーンを具体的にイメージする。
もし開発したソフトウェアの利用者向けユーザーズマニュアルを書く場合、ドキュメントの内容にそれほど迷う事は無いと思います。分からない機能や、状況によって動作が異なるものについては都度検証しながら書いていきますが「ソフトウェアの利用者」がPCの前で「ソフトウェアを利用しながら」マニュアルを参照するイメージが持てます。
これがもし、自分が半年ほど別開発に携わる事になり一時的にチームを離れるため、引き継ぎ担当者は未確定だが、引き継ぎのドキュメントを作る指示を受けたとしたらユーザーズマニュアルのようにスムーズに書けるか疑問です。
- 引き継ぎ担当者が分からない（そのためどこに基準を合わせれば良いのか分からない）
- 開発中の経験は引き継げない（そのためどこで引っかかるのかイメージが持てない）
- 保守なのか新規開発なのか分からない（そのため運用に関する事か機能追加に関する事かどちらか判別が付かない）
(Photo by：Alexis Monville)
このように不明瞭な点が多い場合、全ての状況をカバーするため幾つものパターンを想定するため、準備するドキュメント量が膨大になってしまいます。さらに引き継ぎ担当者の開発スキルの心配までするとキリがなくなります。
もし「引き継ぎ担当者は自分と同程度のスキル」で「保守を担当し新規開発は行わない」と分かれば、保守に関するドキュメントを準備すれば引き継ぎが問題なく出来そうだとイメージが持てます。
また自分は半年後に戻ってくる前提ですので、自分が戻って来た時に困らないためのプロジェクト再開に当たって必要となるドキュメントを準備すれば良い事が分かります。
例え話として、友達と食事に行く時に、中華料理が好きだったかも、和食の方が好きかも、そういえばイタリアンの話もしていたからパスタが良いかも知れない。このような時は、事前にどれが良いのか1つ選んでもらってから料理の注文をしますよね。お店に入ってから中華料理・和食・イタリアンの3つ料理を注文してテーブルに届いた後にどれか1つを選んでもらう注文の仕方はしないと思います。事前に全てのドキュメントを作るのは全ての料理を作ってから選んでもらうのと同じ事です。
ソフトウェア開発のドキュメントも同じように、ドキュメントを必要とする人のためにドキュメントを書くのが最少に抑えるポイントになります。
コードへのエゴを持たず、ドキュメントへのエゴも持たない。
アジャイル開発では、「コードはドキュメントを兼ねる」が「ドキュメントはコードを兼ねない」ためコードを優先する考え方が一時期ありました。
(Photo by：Alexis Monville)
ドキュメントをどんなに書いても、それがコードとして動作する事はありません。そのためこのコードを優先する理由は正しいのですが、書いたコードが読めるものであるとも限らないのが現実です。そのためコードから読み取るのが難しい意図を理解するための「ヒント」をコメントとして文章化する事が求められます。少しのヒントを適切にコード中に含めると、バグレポートや再調査報告書等のソフトウェアの副作用から発生するドキュメントの抑制に繋がります。
設計書・仕様書・要件定義書等のドキュメントも書いてある通りにコードへ変換できるとは限りません。論理的なエラーを多数含み、実装上の制約によって実現不可能な仕様も一定数は発生します。そのためコードと相性の悪いドキュメントは実装上の都合に合わせると、ドキュメントの整合性を保つためのドキュメントが増えて行く状況を抑制する事が出来ます。
最少のドキュメントを作る計画を立てる。
計画を立てたら必ずドキュメントを作る事を迫られドキュメント量が増えると思われるかも知れません。外部からの要望で作る計画外ドキュメントで構成よりも、事前の計画に沿ってドキュメント化を進め、その中で必要とするドキュメントを必要とするタイミングで追加する方が全体のドキュメント量が減る傾向にあります。
ドキュメント計画を立てると言うと、アジャイルの話なのにウォーターフォールのようですが、ドキュメントを書くコストは低く見られがちのため、重要度が高いもので無くとも作れるからという理由で何度も求められる傾向にあります。
(Photo by：Alexis Monville)
そのため計画外ドキュメントは、本当に必要なのか判断し、計画している最少のドキュメント以外の発生を抑制すると、不要なドキュメントの削減に繋がります。
要約・まとめ
開発者視点からドキュメント量を減らすポイントを3つ上げました。「必要としている人に」「必要な価値を」「必要な量で提供する」のがアジャイルやリーン開発の特徴です。
まれに、ビジネスにも開発でも使えて、誰でも理解できるドキュメントの準備を求められる事があるかと思います。このようにビジネス・仕様設計・コードと3つを内包したドキュメントは量が大きくなりがちです。汎用的なドキュメントは便利に見えますが、誰の役にも立たない事があるため「誰でも理解できるドキュメント」を目指すのではなく「相手に届くドキュメント」を意識する事がドキュメント量を減らす中で大切になります。
優れたドキュメントは自分自身を助け、自分の作ったソフトウェアをメンテナンスする人を助けます。ソースコードと同じように、最少で適切なドキュメントを心がけましょう。
本ブログは、Git / Subversionのクラウド型ホスティングサービス「tracpath(トラックパス)」を提供している株式会社オープングルーヴが運営しています。
エンタープライズ向け Git / Subversion 導入や DevOps による開発の効率化を検討している法人様必見！
「tracpath(トラックパス)」は、企業内の情報システム部門や、ソフトウェア開発・アプリケーション開発チームに対して、開発の効率化を支援し、品質向上を実現します。
さらに、システム運用の効率化・自動化支援サービスも提供しています。
”つくる情熱を支えるサービス”を提供し、まるで専属のインフラエンジニアのように、あなたのチームを支えていきます。
