(作成中) アジャイルExcel-想定する文書作成(1) 基本方針

2021年11月30日2022年9月25日

本シリーズで想定している、アジャイル開発における作成文書のイメージを説明する。

基本設計レベルでの文書化は行う

基本設計資料は各種目的に使える

アジャイル開発であっても、日本の多くの開発現場では基本設計レベルでの文書化は必要だと考える。

まず、基本設計レベルの情報は顧客/プロダクトオーナーへの報告、すなわち

• 顧客などへの説明責任

を果たすために必要だからである。しかし、義務的目的だけではなく、以下のようなチーム内でも使用ができ、かつ使用すべきである。

• 基本設計のチーム内での共有
• 基本設計での設計の一貫性担保

「ソースコードを読め」「チケットを辿ればわかる」では非効率で、かつメンバーの力量に依存してしまうからである。

詳細設計やテスト仕様は原則作成しない

これより下位の文書化はソースコードとの二重管理になるため原則として行わない、文書とのトレーサビリティは、ソースコードのREADMEで保証すればよい。

システムテストや結合テストも、仕様や設計の部分部分に一貫性のあるIDを付与し、テスト用プログラムはそのIDを利用すれば、テスト仕様書も原則不要となる。

開発支援文書と納品文書の一体化

想定するドキュメント作成のイメージは、以下のWebページにおける「プロジェクトで働くチームメンバ全員が必要とする文書」と「製品と一緒に出荷される文書」を共通化し、インクリメンタルに作成することに相当する。違いは、優秀な少数の固定メンバーで開発ができるか、そうでないかであろう。

 

必要なときに最低限作成・更新

これらの文書は必要性および開発の段階に応じて作成する。

設計が固まっていくとともに

例えば、初期のイテレーションであれば、システム構成やブロックダイアグラムを作成。イテレーションを繰り返し、要件やアーキテクチャが固まってきた段階で、要件定義などを更新するとともに、データ構成図やモジュール構成図など、より具体的な設計資料を追加していく。

既存システムを解析する際にも

新規システム作成時だけでなく、既存のシステムの引き継ぎなどでシステムの解析結果をまとめるときにも作成する。拡張や障害対応の際のベース資料として使用できるためである。

なお、対象のシステムにすでに文書があった場合も、時間が許すなら無理して流用せず、参考資料に止めるのが吉である。もし、作成の途中で既存文書の品質が高いことが判明したなら、その際に初めて既存文書を流用すればよい。そのようなことは滅多にないが。