ドキュメントをいつかくか？

ドキュメントをいつかくか？

2021年7月25日

ドキュメントをいつかくか？

プログラム開発でドキュメントが必要なのは既にいくつかの記事で書いてきました。この記事では、いつドキュメントを書くのが良いのかを考えてみました。

ドキュメントは後回しになりがち！

会社などでの開発は、開発の「プロセス」があるので、ドキュメントを作成するタイミングは基本的に決まっています。特に、複数の人で開発する場合は、ドキュメントを基にした開発というのが基本なので、ドキュメントは、実際にコーディングに着手する前に作成するのが普通です。
ところが、フリーランスでプログラムを開発する場合、一人で開発する場合が殆どなのでドキュメントが無くてもコーディング上はドキュメントが無くても進めることは可能なので、ドキュメントの作成は後回しになる場合が多いようです。仕事の中心がコーディングだと考えている場合も多くドキュメントの作成はどうしても二番目以降になってしまいます。

会社では、何故ドキュメントを先に作るのか？

では、会社ではなぜ最初にドキュメントを作成するのかを考えてみましょう。幾つか理由がありますが、ここでは二つの大きな理由をあげてみました。
全体の設計と仕事の割り当てをするため
各モジュールのインターフェースの明確な定義
当たり前ですが、全体の設計をしないと仕事の割り当てができません。会社では多くの人が一つの大きな開発に参加するのが普通です。そのために、まずは全体の設計をして、どのよう仕事の分担を決めます。また、全体の機能が明確になるので、テストの計画の開発もプログラムの開発と同時に進める事ができます。
また、各モジュールの設計をするのに必要なインターフェースを明確にして、モジュールの設計が勧められるようにするという重要な役割もあります。
チームで開発をする場合には、こうした全体の「プラン」が必要なのは言うまでありません。
では、フリーランスの開発の場合はどうでしょうか？一人で開発する場合は、その人が全体が見えていれば、問題ないように見えます。

ドキュメントは開発の地図

ドキュメントは、開発の指標です。ドライブする際には、最近はカーナビがあるのであまり考えなくても目的地に行くことが可能です。しかし、全体のルートがわかっていた方が運転する上で便利な場合が多いと思いませんか？
全体のどれくらいまで、来たとか、どこで休憩するかなどドライブのプランを設定するのに役に立ちます。まあ、カーナビの場合は、全体の行程を見ることが出来るので大きな問題ではないと言えます。
しかし、プログラムの場合は、カーナビのように全体見るような切り替えは結構難しいものです。その役割を担うのがドキュメントと言うわけです。

なぜドキュメントが必要か？

フリーランスの開発で、全てを考えるので、ドキュメントは無くても良さそうです。しかし、頭で考えるのは意外に難しいものです。目で見える形にすると考えがより明確にするためです。
まずは、書いて目に見える形にするその役割を担うのがドキュメントです。
ドキュメントを書くことで、考えを整理してまとめると言うのが一番の目的です。例えば、プログラムの機能を実現するのに必要な処理があるとします。その処理をどのモジュールで行うかを決める際に全体のモジュールが目に見える形になっていると、どこで処理をするのが一番良いのかを特定しやすくなります。これが頭の中だと、ハッキリイメージできない場合も結構あります。
プログラムの全体を可視化すると言うのがドキュメントの役割です。
従って、ドキュメントを書く際には、まずは、頭の中のものを出来るだけ詳しくドキュメントに書き出すことが大切です。
一人で開発する場合でも、ドキュメントがある場合は、ドキュメントが共同開発者の役目をしてくれます。
頭の中で考えている場合は一人ですが、頭の中からアイディアを出してドキュメントにすることで、頭のなかでは隠れていることも見えてくる可能性が高くなります。

まとめ

ドキュメントを作成すると、フリーランスで一人で開発する場合でも、貴重な相棒になってくれます。相棒は、開発の最初からいた方が良いと思いませんか？
ドキュメントは、開発の最初から開発が終わった後も、作成したプログラムを語る唯一の相棒です。人間の頭では記憶できない事も開発で終わった後も覚え続けてくれる貴重な相棒です。最初の段階から、頭の中のものをドキュメントに書いておけば、その「歴史」も残るという事です。
相棒は出来るだけ早い段階で開発に参加してもらうのが重要です。そうすることで、開発に大きく貢献するものになります。ドキュメントをキチンんと残すことで、開発の道標としての役割を果たしてくれます。

コメント