ドキュメントのガイドライン

ドキュメントは、情報が属人化して特定の人に負荷が集中することを避けるとともに、情報の共有によってコミュニケーションを円滑化し、新しいメンバーの調査時間を削減したり、メンバー間の認識の齟齬による混乱を防止したりするのに役立つ。

ドキュメントは、読み手が必要な時に必要な情報を提供してこそその価値を発揮する。新たにプロジェクトに参加した開発者であれば、プロジェクト固有の情報や作業の進め方をドキュメントを通して知ることができ、わずかなサポートのみで一人で活動できるようになるのが理想的である。開発に必要なドキュメントとして代表的なものを以下に示す。

最初の頃はドキュメントが整備されていない場合も多く、新メンバーは詳しい人から聞き出す必要が生じる。また、ドキュメントがあったとしても古い情報や記載ミスがあるかもしれない。ドキュメントが不十分であったり、記載されている内容が誤っていたりすることに気づいた時は、ドキュメントを育てるチャンスである。以下のようなルールを決めておくと良い。

ドキュメントを育てるためには、読み手でもある開発者自身がドキュメントを更新できるようにしておくことが望ましい。ただし、好き勝手に変更できると誤った情報が含まれてしまう可能性が高くなるので、変更後にレビューを受けるような仕組みが必要である。