4 - Documentation

Throughout your research, you make many choices, from topic to methodology, from techniques to measurements, from data source to storage format. The choices you make at one stage will affect the choices you make at the next.

For your research to be reproducible in the future, even by you, all those choices need to be documented and available.

There may be more than one valid way to collect and to analyse data but if the same choices are not made later, the result may be different. Methods can vary, equipment may measure and record differently, approaches may have inherent biases for which adjustments need to be made. Each data point needs to be interpreted in the context in which it was collected.

The choices made at the time may seem obvious, but it may not be so in future. Choices are often limited by methodology or technology but both may undergo changes or digital disruption after the project is over, or even during the project.

Within a research group, another possible disruption is the loss of one of the members of the team. If that happens with someone whose role or skills are crucial to the project. Comprehensive documentation can be crucial to the future of the project when someone new takes over that role.

Documentation to safeguard the project

Documentation also reduces the risk to a research team from a low Bus Factor.

The Bus Factor is the number of people who, if they were suddenly lost to the team (e.g., if they were hit by a bus), would cause a major disruption to the project and would compromise the entire research process. It is also called the Lottery Number, which has a more positive connotation but the threat to the team remains the same.

Individual circumstances can change suddenly and if it should occur to one member of the team whose loss would cause major disruption, that is considered to be a Bus Factor of 1. The smaller the number, the greater the danger to the project. The number of people that would have to be lost for the research project to fail must be as high as possible.

As an example, Terry is responsible for the coding for processing and analysing the data for a team project. To the rest of the team, his ability in coding is impressive, and they don’t believe they have the skills and aptitude to do this work so they rely upon him to lead in this process. Terry enjoys his work and his status within the group.

One day, Terry announces that his wife has been offered a lucrative position overseas and Terry is resigning. Suddenly, most of the knowledge of Terry’s role will be lost to the team. Without careful management, a major change to a research team could be more than just disruptive; it has the potential to corrupt the entire project.

Comprehensive documentation is the major strategy for minimising the disruption.

How?

Internal Resources

• Atlassian Confluence - COMING SOON
• Sharepoint at Griffith
• Research Space
• Griffith’s Gitlab wiki options - talk to eResearch Support or Hacky Hour

External Resources

• British Ecology Reproducibility Book
• How to start Documenting and more by CESSDA ERIC
• Software Carpentry Git Workshop