Reproducible Research: Documentation, Version Control and Transparent Workflows

Define what should be reproducible

Reproducibility concerns whether a research result can be regenerated using the relevant data, code and documented procedures. Terminology varies across disciplines, so state what you mean. Distinguish rerunning an analysis from conducting a new study to examine whether a finding holds in another sample or setting.

Begin by identifying the outputs that matter: tables, figures, model results, coded summaries or derived datasets. Then trace the inputs and transformations required to produce each one. The objective is a transparent chain of evidence, with enough information for an authorised person to understand and check the work.

Organise the project from the start

Create a clear structure for original data, working files, code, documentation and outputs. Preserve originals and avoid editing them silently. Use consistent naming and record the purpose of each folder. Separate material that can be shared from information requiring restricted access.

A README should explain the project, file structure, dependencies and how to reproduce key outputs. Write it while the workflow is fresh. Instructions such as run the usual script are not helpful to someone outside the team. Include the expected order of steps, input requirements and known limitations.

Record changes and decisions

Version control helps track what changed, when and why. The Turing Way explains its role in managing histories of research files and collaborative work. ^[1] A suitable system can support review and recovery, but it needs a workflow that team members understand.

Use meaningful change descriptions and distinguish exploratory work from approved releases. Record decisions about exclusions, transformations and model choices. For files not well suited to a particular version-control tool, use an appropriate alternative with clear version identifiers and provenance. The principle is traceability, not the compulsory use of one product.

Capture the computational environment

Record the software, packages and relevant versions used in analysis. Include configuration details and random seeds where appropriate. Document external services or datasets that may change or disappear. The Turing Way's environment guidance highlights the need to capture the conditions under which analysis was performed. ^[2]

Test the workflow in a clean environment or ask a colleague to follow the instructions independently. A script that runs only because its author has an undocumented file on a laptop is not yet reliably reproducible. Check whether outputs match expectations and whether any differences are understood rather than dismissed.

Illustrative example: rebuilding a programme evaluation

Suppose an analyst prepares a chart showing completion rates by programme. The chart was originally made through several manual spreadsheet edits. Six months later, another colleague cannot determine whether withdrawn students were excluded or whether a formula used the correct denominator.

A stronger workflow preserves the original extract, documents eligibility and missing-data rules, and generates the chart from a recorded analysis script or auditable sequence. The output is linked to a dated data version and a review note. A colleague can rerun the process and compare totals, making errors easier to detect before the chart informs a management decision.

Combine automation with meaningful checks

Automating analysis reduces some opportunities for accidental inconsistency, but it can also reproduce the same error repeatedly. Add checks relevant to the data: expected ranges, duplicate identifiers, missing categories and reconciliation of totals. Review a sample of transformations against original records.

Separate computational correctness from substantive validity. A perfectly reproducible analysis may still use an unsuitable measure, biased sample or incorrect model. Independent review should therefore examine both the workflow and the reasoning. Document checks and unresolved concerns so future users do not mistake a successful execution for complete scientific validation.

Prepare a reusable research package

• A README explains purpose, structure and execution steps.
• Inputs are identified with appropriate access conditions.
• Transformations and analysis decisions are recorded.
• Software and environment requirements are specified.
• Outputs are connected to the relevant code and data versions.
• Quality checks and limitations are documented.
• Sensitive information and credentials are excluded from public releases.

Before sharing, ask someone unfamiliar with the project to use the package. Their difficulties reveal missing assumptions that the original team may no longer notice. Preserve a stable release alongside the publication or report and explain how later corrections will be handled. Reproducibility becomes sustainable when it is part of daily work rather than an emergency task at submission.