変更に強いドキュメントの心得
~アジャイルでのドキュメントとの付き合い方~
アジャイル開発をしていて「包括的なドキュメントよりも動くソフトウェアを」とドキュメントを蔑ろにしていませんか？
アジャイル開発での”ドキュメント”とは何かを考え、円滑なアジャイル開発をしていきましょう。
この記事は アイソルート Advent Calendar 22日目の記事です。
■はじめに
”アジャイルはすべてがドキュメントである”
こんにちは。
webソリューショングループでアジャイル開発をしているkaneko.kです。
アジャイル開発では仕様がスプリント毎のフィードバックを経て変化していく開発手法なため、かっちりしたドキュメントを作成し辛く、修正コストも嵩みやすいと感じていませんか？
もちろんしっかり管理できるチームもあるかとは思いますが、ドキュメントの修正コストが高いがために「本当は変更したいんだけど、ドキュメントを更新するコストが捻出できずに変更をあきらめる・・・」なんてことにはなっていませんか？
あるいは作成するドキュメントを最小限にしようとするがあまり本来作成しておくべきドキュメントが手つかず・・・なんてことにはなっていませんか？
今回はこれらアジャイル開発が抱えやすい”ドキュメントにかかわる課題”の解決糸口になればと思います。
※アジャイル開発ってどんな開発なの？という方は是非こちらも合わせてご覧ください。
blog：銀の弾丸ではない アジャイル開発を正しく理解をしよう
■ドキュメントの種類
ドキュメントは大きく分けて
- 開発するために必要なドキュメント
- 利用者向けのドキュメント
- 契約上必要なドキュメント
- 運用保守のためのドキュメント
に分類できます。
下3つのドキュメントに関しては各プロジェクトや会社間での取り決め等で作成するものが決まっていることが多いため、工夫の余地がほとんどないかと思われます。
今回は一番上「開発するために必要なドキュメント」に焦点を当ててご紹介していきます。
■ドキュメントのコストと追従性
「開発に必要とは言えメンテナンスは大変だし、変更が入ることが多いドキュメントはなるべく作らないべきでは？」
日々(あるいはスプリントごとに)お客様からフィードバックを貰い改善していくアジャイル開発ではせっかくドキュメントを作っても何か改善を入れる度にドキュメントも修正が必要になり、コストがかかってしまいます。
そのため変化が特に多くなる画面仕様書や設計書＊1などは開発中に作成することを極力避け、納品の際に必要であれば作成するという方法をとられることが往々にしてあるかと思います。
とは言え、開発中に画面仕様書がないと画面の認識齟齬が起きやすいですし、設計書がないと「なぜこの設計にしたのか」が分かりづらくなってしまいます。
こうした二律背反の中で十分機能する変更に強いドキュメントを作成していくためには「かっちりしたフォーマットが決まったドキュメント」からの脱却が必要になってきます*2。
1）「設計書は後からそんなに手が入らないのでは？」と思われるかもしれませんが、案外開発を進めていくと「やっぱりこの画面にこの情報も一緒に出したい！」となるものです。その度に設計書を見直さなければなりません。
2）もちろんフォーマットを決めることが悪と言う訳ではありません。ドキュメントの特性上フォーマットが決まっていたほうが良い場合はあらかじめ決めておくべきです。
■ソースコードは重要なドキュメントである
「ありとあらゆる開発手法の中で最も最新の仕様に追従しているのはソースコードである」
ソースコードはあらゆる情報を提供してくれます。
- 各機能の最も詳細な振る舞い
- 具体的な画面の見え
- ワークフロー
- 各画面や機能の役割
- 各機能の閾値での振る舞い(テストコード含む) etc…
開発者にとって最も分かり易く信頼できるドキュメントはソースコードであることが多いですし、むしろソースコードはそうあるべきと言う人も多いことでしょう。
ソースコードがドキュメントとして機能すれば急な引継ぎがあった時もスムーズに引き渡せますし、コードを変更するたびにドキュメントに手を入れる手間が省けます。
- ”なぜ(理由)”が書かれたコメント(トリッキーな、あるいは論理の飛躍があるコードを書かないことに成功した場合はコメントは不要)
- I/Oのしっかりと書かれたJavadoc
- 名前を見ただけ役割や目的がわかる命名規則
- 統一的かつ整合的なレイアウト
- 疎結合で簡潔なロジック
これらを開発者一人一人が守って書くためにはやはり「動くソフトウェア」という意識ではなく「コードもドキュメントなのだ」と強く認識する必要があるのです*3。
*3）この辺りの具体的な手法についてはかの有名なリーダルブルコードあたりが参考になります
■Gitも立派なドキュメント
「なぜ変更したのか、どうしてバグが起きたのか」
ソースコードの重要性については多くの方々が語っている通りですが、ソースコードの「変更理由」と「バグの理由(解析結果)」についてはソースコードでは分かりません。
これらの問題をいちいち資料化することなく端的に、また継続的に行うことができるのがGitやSVNなどのバージョン管理ツールです。
変更前の状態を保持しておくために導入しているプロジェクトも多いかと思いますが、これらバージョン管理ツールをただの”バージョン管理だけ”で終わらせるのは非常にもったいないです。
特にGitはGitHubやGitLabなどの リポジトリホスティングサービスが充実しており、単なるバージョン管理やソースコードレビューだけでなく「コードの変更経緯」や「バグの理由(解析結果)」をコミットに紐づけることができます。
コミットメッセージやイシューをドキュメントとして意識したうえで書くことで、余計な”ドキュメント”を作成しなくても済むよう心がけていくことが肝心です。
■文字に起こされたものだけがドキュメントじゃない
「画面仕様書など文字で表現しづらいものは？」
画面、特にデザインが絡むところはアジャイルだと特に変更が多いためドキュメントを最新化していくのに非常に多くの労力を要します。
そこで役に立つのが写真やスクリーンショットです。
ホワイトボードに書いた簡単な絵でもいいですし、すでに動く画面がありそこへのデザイン改修等でしたらスクリーンショットにコメントや絵を挿入する程度でも構いません。
とにかく認識齟齬を防ぐためにも少しでも情報は形にして残しておくのが重要です。
画像ファイルの管理方法はいろいろあると思いますが、個人的におすすめなのはRedmineやJIRA等のプロジェクト管理ツールで管理することです。
チケットに添付という形で保存することによって写真だけでは伝えきれない情報も手軽に残せますし、何より検索や絞り込みに優れます。
またwikiやファイルサーバで管理することも可能ではありますが、変更履歴や経緯なども一緒に残せる「チケットに添付」方式は非常におすすめな方法ですのでぜひご検討してみてください。
■さいごに：アジャイルはすべてがドキュメント
ここでご紹介できた内容はほんの僅かですし、もうすでに実施している内容ももしかしたら多かったかもしれません。
しかし今一度、「すべての作業がドキュメントとして成り立っているか」を見直して、”資料”以外で担保できる(あるいはすでにできている)”ドキュメント”がないか探してみてください。
きっとドキュメント周りで起きていた問題の解決の糸口になるかと思います。
あなたが良きアジャイル開発ライフを送れることを。
以上kaneko.kがお送りしました。
■次回
明日はfukatsu.hさんの「【Dialogflow】ちょっと凝ったチャットボットを作りたい人が読むシステム構成の話」です。
