はじめに

「アジャイル開発では包括的なドキュメントよりも動くシステムを重視するからと言って、全くドキュメントを作成しなくてよい、というのは必ずしも正しい認識ではありません。」（政府CIOポータル）
ドキュメントの整理の仕方の具体的なところは載ってなかったから、個人的な体験談を踏まえた整理ポイントを残してみた。

公式っぽい情報

会社ブログとか個人ブログとかはいっぱい引っかかった中で一番公式っぽいのがこちら。
書いてあることはまさにそれって感覚。

アジャイル開発実践ガイドブック

2021 年（令和３年）3 月 30 日
内閣官房情報通信技術（IT）総合戦略室

各種ドキュメントについて

アジャイル開発では包括的なドキュメントよりも動くシステムを重視するからと言って、全くドキュメントを作成しなくてよい、というのは必ずしも正しい認識ではありません。
ドキュメント作成が重視されがちなウォーターフォールと比較して、不必要なドキュメント（保守工程で参照される機会があまりなく、ソースコードでも代替できるプログラムの詳細設計書等）は省くという姿勢はありますが、例えばシステム全体の概要を認識するための構成図や基本設計、ERD やエンティティの定義、システム境界のインターフェース等をドキュメント化することはしばしば運用・保守や改修に役立ちます。

また、ウォーターフォールでは、情報システムを開発する前にドキュメントを作成して、要求や仕様を言語化しますが、アジャイル開発では、動くシステムによって要件を調整したり変更したりするため、ドキュメントの作成は主要な機能の開発後や運用開始前に行うことも多くなります。
ドキュメントを作成しながら開発を進めることを妨げることはありませんが、構築した情報システムを基にドキュメントを作成する方が効率的なことも多く、開発の前や開発と並行して作成するドキュメントと、プロジェクトの後半又は終盤に作成するドキュメントとを見極め、後者のためにプロジェクトの後半又は終盤に作成期間をまとめて設けることが望ましいです。

ポイント整理(自己解釈)
少しニュアンス変わってる自覚はある

運用・保守に必要なドキュメントを作る
要件や仕様の確認において、ソースコード（動くシステム）で確認を基本とし、ソースコードで確認が難しい部分をドキュメントでカバーする。
システムをある程度作ってから作成した方が効率的なドキュメントと、開発時の認識齟齬を埋めるためにシステムを作る前に必要なドキュメントと見極める必要がある。

個人的な整理の流れ

決めるべきこと

どのような情報を残すべきか
その情報をどのような形式で残すのか
その情報はいつまでにアウトプットされているべきか

例えば以下。

情報：大枠のシステムデザイン
- 形式：miroなどのWEBホワイトボード
- 作成時期：開発着手前
情報：細かい仕様
- 形式：ソースコード
- 作成時期：開発中
情報：保守運用に用いるジョブの緊急停止手順
- 形式：手順書
- 作成時期：運用テスト前

など

例えば、細かい仕様などは、今まで設計書に残していたかもしれませんが、ソースコードで十分という判断をすることはあり得ます。
その判断をどのように下していくのかは、次にまとめてます。

判断ポイント

ということで、どこら辺が判断ポイントになるか以下に整理ます。
今まで書くのが当たり前だった文化だと、今更切り分けろと言われても困る場面が多いと思いますので、何を基準に判断すると良いのかを以下に示します。

従来の設計書のファイル単位で考えるのではなく、設計書の中の部分部分で分けて考える。
開発者だけで判断しない。
誰の何のためにどれくらいの情報が必要なのかを整理する
いつ見るものなのかを整理する。
判断がつかない場合はとりあえず無くしてみる。

従来の設計書のファイル単位で考えるのではなく、設計書の中の部分部分で分けて考える。
ファイル単位で考えちゃうと「必要だね」って結論になっちゃうので、そこを細分化しましょう。
例えば、章立てされているなら、章立てごとに考えるとかです。
これはこの先話すことの全ての前提になります。

開発者だけで判断しない。
これも前提に近い話です。
開発者としては不要でも、法令対応のために残す必要があったり、ステークホルダーと合意するために必要なドキュメントなどは存在します。
開発者体験みたいな話もありますが、それはビジネスが成り立った上で、追求していくものなので、ビジネスとして成り立たせる最低限のドキュメントは作成する必要があります。
（自分も余計なドキュメントは作りたくない）

誰の何のためにどれくらいの情報が必要なのかを整理する
「誰の」「何のため」「どれくらい」の３つを整理する。

誰のは、例えば、顧客がみるのか、開発者がみるのか。
何のためは、例えば、「顧客がステークホルダーと仕様を合意するため」とか。
どれくらいは、例えば、「〜桁以上、〜桁未満かつ使える文字種は〜であること（詳細な情報）」なのか「文字精査をする（粗い情報）」なのか。

顧客が詳細な情報を見るのに、ソースコードという形式が妥当なのか？というのは判断が一つあると思います。
とはいえ、ソースコード見てくれという気持ちは正直あるので、ドキュメント作成コストと読解コストを顧客に天秤してもらう形になるかと思っています。

いつ見るものなのかを整理する
リリースした後にようやく参照されるものを、開発初期に作る意味はないです。
ただ、人間なので、記憶の劣化もあるため、保守後に必要だけど、忘れそうだから今作っておくか・・・ってのはあると思ってます。

判断がつかない場合はとりあえず無くしてみる。

イーロンの全てを賛美するわけじゃないですけど、この考えはもっともだなぁと感じたので、紹介です。

要件定義を聖書のように扱わず、常に疑ってかかる。
プロセスをできるだけ削る
最適化する
高速化する
自動化する

とにかくドキュメントの存在意義を疑う。とりあえず無くす。
無くして問題が生じたなら、それは必要なドキュメントだ！

くらいのスタンスでバッサリ行きたい。
当然、「無くすとこの問題が絶対に生じる！」とわかっているのであれば、無駄に無くす必要はないと思います。
ただ、判断つかないものは、とりあえず無くしてみようぜ！みたいなスタンスで減らしていく方が、改革は進むかと思っています。

まとめ

決断すべきこと
- どのような情報を残すべきか
- その情報をどのような形式で残すのか
- その情報はいつまでにアウトプットされているべきか
決断のポイント
- 従来の設計書のファイル単位で考えるのではなく、設計書の中の部分部分で分けて考える。
- 開発者だけで判断しない。
- 誰の何のためにどれくらいの情報が必要なのかを整理する
- いつ見るものなのかを整理する。
- 判断がつかない場合はとりあえず無くしてみる。

次回予告

本記事は、2022アドベントカレンダー「受託アジャイル」の記事です！他にも興味あれば見てってください。
次回は、アジャイルのダークサイドです。

以上です。