システムの開発や運用において、ドキュメントを作成するのは大事な仕事です。最近ではアジャイル開発の認知も高まってることもあり、ドキュメントに価値がないと思われがちですが、必要なドキュメントは作成しないと開発や運用の妨げにもなりうると私は考えています。
とは言え、じゃあ何のドキュメントが必要なんだと言われると、かなり答えに窮してはしまいます。最適解は現場によって異なるだろうし、画一的にこれがあれば大丈夫と言えるものがないのが、難しいところではあります。また、下記の記事にある通り、ドキュメントは陳腐化しやすいものなので、いかにメンテナンスしていくかという観点も非常に重要です。
そもそも、ドキュメントは何のためにあるのか。一つの目的としては正しい情報に早くたどりつくため、というのが挙げられると思います。ドキュメントだけ作っても、正しさがある程度担保されてないと、無駄な遠回りが発生するでしょう。とはいえ、完璧にするのはやはり難しいので、読み手側も以下の記事にあるような観点で、内容の妥当性を吟味するのは大事だと思います。
また、ソースコードや設定を確認すれば、わざわざドキュメント作らなくても開発は進められる、という考え方の人もいるでしょう。私も極力ドキュメントを書くのは減らしたいと思ってはいるので、気持ちはメッチャ分かります。ただ、以下の記事で触れられているような、
どういうドキュメントを必要最低限で残していくかは、残しながら「これはやっぱり必要だったね」と精度をより高めていく活動が必要だと思います
という意識は大事だと思います。必要なドキュメントが何かという考慮なく、とりあえずドキュメントを作るもしくはドキュメントを作らない、と決めてしまうのはやはり避けたいところでしょう。ドキュメント整備の時間をとる現場もあると思いますが、まずはその前段として「ドキュメントがなくて困ったこと」を共有するのが大事な気はします。
また、以下の記事で触れられていますが、ドキュメントは作成して、すぐに効果が出ないということはありがちと感じます。なので記事に書かれてるような、
未来のための資産を残す想定でドキュメントやコメントを残すモチベーションとしている
のような考え方も大事と思います。これも何を残す残さないは、そのチームで何が困ったかという認識がないと、中々判断は難しいと思います。なので、困り事を共有して意識するというのは、ドキュメントを整備する前段として必要かなと考えています。
というわけでつらつら書いてしまいましたが、今回私が書きたかったことをまとめると以下の通りです。
・ドキュメントは、情報を把握するための手助けとなる。
・そのために、必要なドキュメントは作成すべき。
・何が必要かはチームや状況によって異なる。そのため、ドキュメントが必要となるような困り事について目を向ける。
・ドキュメントは、作成してすぐに効果が出ない可能性がある。なので、将来のためという観点も持つ。
