ドキュメントを誰のために書いているか

コンピュータでやりたい自動化の仕事を、いろいろな要素を組み立てて、最終的になんとかやれるようになったとします。プログラムとか、Accessプロジェクトとか、なにか専用の動作をさせるための機械とかの組み合わせです。こういうのをみんなあわせて、ひとつのシステムと呼んだりします。

そのときには、当然ながら、やったこと全体を説明するドキュメントが必要です。操作マニュアルも重要なドキュメントのひとつではありますが、それだけでなく、どうしてこのシステムが存在するのかを全て説明するドキュメントです。

もっと具体的には、どういう問題を解決するために、どういう根拠でそれぞれのシステム構成要素やプログラム言語・ライブラリが選ばれたか、それらはどういう条件で正常に動作してどういう条件で動作しなくなるか、何を見ることで動作が正常と知ることができるか、などです。

書いたプログラムやスクリプトも、ひとつひとつをすっかり説明すべきです。１本のプログラムごとに、丁寧に整形され、変数名、関数名、パラメータ名が合理的で、細部にわたって、書かれた根拠が明確に説明されていないといけません。のちに動作内容を調整したくなると予想される箇所があれば、それを作り込みやすいようあらかじめ工夫し、その意図を明記しておかなくてはいけません。ExcelやAccessのように、プログラムコードに相当するものが数カ所に分散してしまうタイプのものは、それらがどこに配置されているかも含め、あいまいな点がひとつも残らないよう工夫されていないといけません。

結果として、システムの構築について勉強している人がもしもいたときに、ほとんど教材のように使える程度の品質をもったドキュメントが求められると考えています。

こうして整備されたドキュメントは、実は、それを納品した自分自身のために最も役に立ちます。けっこうな時間が経ってしまったあとで、システムの一部を修正したり、動作内容を変更したり、または動作の不具合と思われる点を調査する必要が生じるということは必ずあるのですが、その際、手がかりなしに当時の記憶をすっかり取り戻せるとは期待できません。そのときの記憶をできるだけ生々しく脳内に「ロード」するために、完璧なドキュメントがその役割を果たします。

自分自身のためであるという一方、このドキュメントは、のちにシステムを他人に託すためにも必要なものです。自分が永久にそのシステムのアフターケアをできるわけではありませんから（事故なんかでそれが不可能になってしまうことだってあり得ます）、誰かへの引き継ぎが必要になったときに、その労力を考えられる限り軽くするためにも、ドキュメント作成に手を抜くわけにはいきません。これがなければシステムは不完全なものだ、と言っても、言い過ぎではないはずです。