Documentation and Cross-training


See Releng RFC 0007 for best practices in creating and linking documentation.


Bus factor

It’s important to cross-train other team members, so no critical area of knowledge has a singleton contributor. The team needs to provide coverage during PTO, sick leave, timezones outside of the owner’s working day.

Should we need focus time to finish an important project, other team members can provide cover from interrupts, but only if we’ve written the documentation and cross-trained the team.

Use cross-training to test documentation

Ideally, documentation can provide enough information and direction to understand and fix problems without additional context. One way to check this is to write the documentation with this in mind, then cross-train by pointing the trainee at the documentation. You’re available to answer questions and clarify, but any needed clarification means the documentation may not be complete or understandable. Update the docs with this new information.