開発や営業、様々なシーンでドキュメントを書く必要はある。
ドキュメントなしにして良いものはできない。
最低限、注意しておきたいポイントを自戒の念も込めて書き出しておく。
読みやすさ
読みにくいドキュメントは途中で読むのを断念してしまう。
せっかく時間をかけて書いても、読まれなければ意味がない。
- 誤字脱字がある
- てにをはが不適切
- 日本語としておかしい
- ルールがない
- 文章ばかり
- 複雑な図表がある
理解しやすさ
理解しにくいドキュメントは読んだ気になっても本質が伝わらない。
しっかりと読んだと思っても、後になって矛盾に気づく。
- 主観が多い
- 曖昧な表現が多い
- 理解しきれていない事をわかったように書く
- コピペしてそのまま
- 結論が無い
- 一文が長い
- 事実と意見と評価(良い、悪いのような表現)が混ざっている
- 専門用語が多い
- 一貫性がない
納得しやすさ
納得できないドキュメントは承認されない。
読み手を意識していないことで、期待を裏切ってしまう。
- 目的と背景を説明せず、伝えたいことだけ書く
- 誰向けのドキュメントか定義していない
- 読み手のスキルレベルと合っていない
レビューしてない
よいドキュメンテーションは人の目に触れて、フィードバックを受けることでより良くなる。
一方的なドキュメンテーションにならないよう、コミュニケーションにより品質を保つ意識が大事だ。