システム開発のドキュメントは『いつ・どれくらい』作るべき？
「どうせ後で仕様変更するんだからドキュメント書くだけ無駄じゃね？」
「そもそも作るべきドキュメントの正解が分からない…」
システム開発において「ドキュメントをどれくらい作るべきか？」って永遠のテーマですよね。絶対的な正解はなくてプロジェクトによって変わりますからね。
私なりの考えを紹介します。
Contents
ドキュメントには2種類がある
開発に必要なドキュメントと、運用に必要なドキュメントです。
開発用ドキュメント
システムを開発するにはシステムの要件を定義して、そこから機能を導き出し、詳細化してプログラムの仕様に落とし込み、システムを実装します。
前工程のドキュメントを元にして次の工程のドキュメントを作成します。最終的にはプログラムの仕様書が出来上がり、それを元にプログラムを作るわけです。
つまり要点は、次の工程を進めるためのドキュメントを作るということです。
運用用ドキュメント
こちらは開発に必要なドキュメントとは性質が異なります。
次の工程のドキュメントを作るためのドキュメントではなく、システムを運用するのに必要なマニュアルを作ります。
ですから、運用する人が分かるように書くことがポイントです。運用する人がアルバイトの学生やIT知識のないパートのおばさんの場合もあります。
- 専門用語をできるだけ使わない
- 誰が読んでも同じ解釈ができるように書く
などの配慮をするとよいでしょう。
顧客に開発ドキュメントと運用ドキュメントの『違い』を認識させる
顧客の中にはこの違いがわかっていないため、開発用ドキュメントなのに、
- 非エンジニアが読んでも意味が分かるように書いてくれ
- 図などをもっときれいに書いてくれ
などと要求してくる人がいます。これは明らかに間違いです。
開発用ドキュメントは、開発に使うものなのでエンジニアが読むものです。ですから、エンジニアにしか分からない専門用語を使って構わないし、図形の線がちょっとくらい曲がっていたり、見栄えが悪くても構わないのです。
運用ドキュメントはシステムが完成してから作るべし
顧客の中には、「開発時に作ったドキュメントを運用でも使えるようにしたい」と言う人がいます。「仕様書にはシステムの機能の説明があるのだから、運用でも使えるはずだ」という主張です。
これも間違いです。なぜかというと、
１．仕様書には運用に関係のない情報が多すぎる
運用に必要な情報はシステムの「使い方」です。
仕様書を読めば確かにシステムの使い方は分かりますが、仕様書にはシステムの「作り方」、実装方法が書かれています。
実装方法を読んでシステムの使い方を理解するのは非常に難しく効率が悪いです。
２．システムが完成するまでに仕様変更が多かれ少なかれ必ずある
仕様書に運用に役立つ情報（システムの使い方等）を追加で書いていくとします。
開発の途中で仕様が変わると、システムの使い方の説明も変えなければなりません。
ですから、運用マニュアルは開発が終わってから作るべきなんです。
話の通じない顧客に対処する方法
- 「自分が楽をしたいからドキュメントを減らそうとしてるんじゃないか？手抜きだろ？」
- 「俺は客なんだ、なんでお前らの意見を俺様が聞かなきゃならないんだ！？」
こんなことを言う顧客は実際います。この場合どうすればいいでしょうか？
私なら転職します。
私も今まで散々顧客を変える努力をしたことがあります。丁寧に必要なドキュメントとそうでないものの違いを説明しました。
しかし、聞く耳を持たない人っています。ですから、こちらから提案して、懸命な説明を尽くしても、受け入れられない場合は、別の職場に移ることが賢明です。
自分に合った職場って探せばちゃんとありますからね。