アジャイル開発でドキュメント作成は必要？書き方のポイントを解説

アジャイル開発におけるドキュメント不要は勘違い！

2001年、アメリカユタ州で生まれたアジャイル開発という概念。公式文書である「アジャイルソフトウェア開発宣言」のなかで、アジャイル開発における価値のある開発手法について、まとめられています。

そのなかに「包括的なドキュメントよりも動くソフトウェアに価値を置く」という一文があるため、要件定義書や設計書などのドキュメントを書かなくてもよいと捉える人が少なくありません。

しかし、これは後に続く「左記のことがらに価値があることを認めながらも、私たちは右記のことがらにより価値をおく。」という一文から、相対的にいえば「動くソフトウェア」により価値を置くが、「ドキュメントを書くこと」自体に価値がないわけではないことを意味しているのです。

実際、アジャイル開発においてドキュメントが存在しないことで、作業が属人化したり、メンテナンスしづらいものであったりと不便が生じるケースもあり、ドキュメントの作成は必要であるといえるでしょう。

参考：アジャイルソフトウェア開発宣言

アジャイル開発におけるドキュメント作成の必要性

では実際にドキュメントを書くことは、アジャイル開発においてどのような役割があるのでしょうか。その必要性について解説します。

関係者同士のコミュニケーションを円滑にするため

アジャイル開発ははじめに綿密な計画を立てない分、開発段階では臨機応変な姿勢が求められ、チームや顧客とのコミュニケーションが欠かせません。その際、ドキュメントの活用は有効な手段です。

ソフトウェア開発においては、まだ形になっていないものを関係者で共有・理解し、お互いに意見をぶつけてよりよいものにブラッシュアップする必要があります。

しかし、口頭だけでは伝えきれない部分が多いでしょう。ドキュメント化して共有することで、話し合いの質が向上します。新しい発想を促し、アイデアが関係者に理解されやすくなるでしょう。

開発に関わる情報を誰もが理解しやすくするため

開発に携わるメンバーは、決して少なくありません。直接開発プロジェクトの進行を担うメンバーはもちろん、顧客や、将来保守や改修に携わる人も含まれます。またメンバーの立場によって情報の理解度は変わります。

単にソフトウェアの内部構造を把握するだけであれば、ソースコードを見れば事足ります。しかし、ソフトウェアに要求されている拡張性や保守性など、抽象度の高い概念はコードだけではわかりません。

ソースコードとは別に、ソースコードに込められた「意図」「考え」「思い」をドキュメント化することで、開発者本人はもちろん第三者でも全体を俯瞰でき、開発・保守・改修が行いやすくなるのです。

開発の進捗状況を可視化するため

ソフトウェア開発は、最初に予定した通りに進むものではありません。途中で変更が求められるケースも多いでしょう。

変更を検討する際にドキュメントがあれば、変更後の計画と開発スケジュールへの影響を可視化できます。つまり、ドキュメントは関係者が変更について理解・納得するための足がかりとなります。

また正確性や効率性など、相反する要素を両立させる必要があるため、ドキュメントに正確性を求めすぎないことが大切です。変更することを前提とした柔軟性の高いドキュメントを作成しましょう。

ITトレンドでは、さまざまな開発ツールを取り扱っています。以下のボタンから無料で資料請求できるので、比較検討する際にぜひご利用ください。

アジャイル開発で利用されるドキュメントの種類

アジャイル開発で用いられるドキュメントは１つではありません。一般的に、以下の４種類に大別されます。

開発者用

設計書など、開発者がソフトウェア開発を行ううえで必要な情報をまとめた書類

利用者用

顧客とソフトウェアに関する認識を共有するための書類

契約用

契約に必要な形式的な書類

運用保守用

運用や保守に携わる関係者がソフトウェアの情報を把握するための書類

このうち、開発者用以外のものは、求められる形式がある程度決まっています。したがって、工夫の余地があるのは開発者用のドキュメントでしょう。

アジャイル開発におけるドキュメントの書き方のポイント

アジャイル開発は途中変更を前提として進行します。したがって、ドキュメントの内容も頻繁に改変します。ここでは、ドキュメントの書き方と更新作業におけるポイントについて解説します。

ソースコードをわかりやすく書く

ソースコードは、ソフトウェアの内部構造を最も正確に表現できるドキュメントです。開発者であれば、ソースコードを見るだけで画面や機能など多くのことがわかるでしょう。そしてソースコードはプログラムとして動作するとともに、開発者間で情報を共有するための手段にもなります。

ソースコードがわかりやすく書かれていれば、ソースコードがドキュメントの役割を果たします。つまりソースコードを変更するたびに、ドキュメントを更新する必要はない、ということです。急な引継ぎでも円滑に引渡しできるでしょう。

しかしわかりやすく書くことを意識したソースコードでなければ、プログラムとして機能はしても、人の目には理解しづらくなります。開発者の個性的すぎるコーディングや、データの変更ができない独自のものなどは、異動の際に後任の担当者が頭を抱えることになるでしょう。

ソースコード内にコメントを残す、トリッキーな構造にしないなど、他者が見た際にわかりやすいよう工夫が求められます。

メンテナンスを行いやすいものを作る

システムはその時々で変化していくため、システムにあわせたドキュメントを書く必要があります。

ソースコードを、「誰が見てもわかりやすいものを書いて残す」ことに加えて、後々のメンテナンスを考慮したドキュメントを作成しましょう。例えば、修正した箇所がすぐに見つかる仕様にしたり、履歴を残しやすくしたりするなどの工夫が必要です。

バージョン情報を詳細に残す

ソースコードには、ソースコードを変更した意図を残せません。ドキュメントとして別途残すことは可能ですが、大きな手間となるでしょう。

そこで有効なのがバージョン管理です。バージョン管理ツールなどを活用し、バージョンの情報を詳細に残せば、それをドキュメントとして活用できます。変更時期や、変更の理由となったバグの詳細も保存できれば、資料としても充分利用できるでしょう。

このように、バージョン情報などドキュメントとして有効なものを活用することで、ドキュメントを新規作成する負担を削減できます。

デザインなどの写真や画像を残す

文章化したものだけがドキュメントではありません。

画面仕様書のように、視覚的に伝えたほうがわかりやすい場合は、積極的に画像を活用しましょう。画像データはもちろん、手書きのメモなども写真に撮って共有してください。文章化する手間を省けるうえ、抽象的な概念の共有も行いやすくなるでしょう。

また、それらの画像データは、誰もが閲覧できる状態にしておく必要があります。またドキュメント管理ツールや開発ツールで管理することで、さらに効率化できます。

なお、開発ツールはドキュメント管理機能のほかに、スケジュール管理や進捗状況の把握、コミュニケーションなどの機能を搭載しており、アジャイル開発を円滑に進めるのに役立つでしょう。

アジャイル開発でのドキュメント作成を効率化しよう！

アジャイル開発において、関係者間のコミュニケーション円滑化や認識齟齬の防止、進捗状況の共有などの観点から、ドキュメントを書く必要性は十分にあります。ドキュメントを書く際には、ソースコードをわかりやすく書いたり、バージョン情報を残すなど、他者が見てもわかることを意識し、作成しましょう。

加えて開発ツールを活用すれば、ドキュメントの作成や管理が円滑化します。以上を踏まえ、効率的なアジャイル開発を実現しましょう。