仕事でマニュアルのような手順を記載したドキュメントを書く時、常にメンテナンスを意識しておく必要がある。メンテナンスと言うと抽象的でわかりづらいので、自分の思いつくアンチパターンを雑にまとめておこうと思う。
- タイトルに日付をつける
- 日が経つにつれて似たようなドキュメントが増えていく。1つのドキュメントを常に最新にしておく方がよい
- 補足・修正内容をコメントに書く
- ドキュメントサービスによるが、コメントで補足や修正をすると見落とされる。本文を更新する方がよい
- 定期的に見直すタイミングや担当が決まっていない
- 程度の差はあれ、ドキュメントの内容は必ず古くなる。その前提で定期的に見直すタイミングや担当を決めておく方がよい
- バイネームの記載がある
- 担当が変わって情報が古くなるみたいなことになりがち。ドキュメントだけの問題ではなくチーム課題かもしれない
- 文章が冗長
- これは人によって感覚が違うので難しい。より短い文章で伝えられないかは常に意識した方がよい。タイトルも同様
- 全員見れるべきものが見れない
- 閲覧権限が適切に設定されていないというだけ。見れるべきではないものが見れるよりは全然よいという話ではあるけれど
- スクショの過度な多用
- スクショは古くなりがち。本当にそのスクショがないと伝わらないかを一度検討した方がよい
他にもいっぱいありそうだしもっと整理できそう。色々な意見聞いてみたい。
