新人の頃、ドキュメント作成を「作業の付録」だと思っていました。3年やって、考えが180度変わったので書き残します。
ドキュメントは「未来へのメッセージ」
設計書や手順書は、その場のためだけのものではありません。半年後に障害対応する人、1年後に増設する人、そして未来の自分——彼らへのメッセージです。「なぜこの構成なのか」が書かれていれば、後任は迷いません。
「設計意図」を残すと差が出る
図や設定値は残っていても、なぜそうしたかが抜けている資料が多いです。
- なぜこの冗長化構成なのか（何を守るためか）
- なぜこのアドレス設計なのか
- なぜこの機器を選んだのか
この「なぜ」があると、後から変更するときに、壊していい所と触ってはいけない所が分かります。
書くことで自分の理解も深まる
説明を書こうとすると、自分の理解の穴に気づきます。「なんとなく設定した所」は、書けません。だからドキュメント作成は、実は自分の勉強にもなっています。
良いドキュメントの条件
- 読み手を想定している（誰が、いつ、何のために読むか）
- 図と文章のバランス（図で全体、文章で意図）
- 更新されている（古い情報は害になる）
- 一箇所にまとまっている（散らばると探せない）
面倒でも、その場で残す
「後でまとめる」は、たいてい実現しません。作業とセットで、その場で記録するのがコツです。少し面倒でも、未来の誰か（自分含む）が確実に助かります。
3年目としての実感
技術力は当然大事ですが、それを残して伝えられるかで、エンジニアとしての価値が変わります。個人の頭の中にあるノウハウは、その人が抜けたら消える。ドキュメントにして初めて、チームの資産になります。地味な作業に見えて、実は一番プロらしい仕事だと、今は思っています。