Reproducibility and open science · Lesson 3 of 3

Documentation, versioning and openness

Keep raw data untouched, do everything in recorded steps, and share the layers you legitimately can.

8 min read · Free — no account needed to read

Documentation is what makes your own work usable later. A data dictionary lists every variable: name, meaning, unit, permitted values, how missing data is coded, how it was derived. It takes an afternoon and saves weeks.

Provenance is the record of where data came from and what has happened to it since — collected when, by whom, cleaned how, with which rules. Keep raw data untouched and do all cleaning in a script, so the path from raw to analysed is always visible.

Version control — git, or at minimum a disciplined naming and changelog scheme — replaces the folder full of `final_v3_REALfinal`. It answers what changed, when and why, and it is what lets you return to the state that produced a published number.

Open data means depositing data in a repository with a persistent identifier. Open methods means sharing protocols, instruments and code. Open access means the paper is readable without a subscription.

FAIR summarises the goal: Findable, Accessible, Interoperable, Reusable — with the accent on machine-readable metadata and clear licences, not on making everything public.

And the constraint that must not be glossed: much data cannot be shared. Consent may not cover it, it may identify people, it may be commercially or legally restricted. The answer is not to share it anyway. It is to share what you can — the protocol, the instrument, the analysis code, a synthetic or aggregated dataset — and to state plainly why the rest is restricted and how a legitimate researcher could request access. Openness is a direction, not an obligation that overrides consent.

See it happen

Your ethics approval and consent form do not permit sharing the interview transcripts.

The read that arrives on its own

Open data is not possible here, so there is nothing to share and nothing to say.

The same situation, with this idea

You share what is shareable and say why the rest is not. The interview guide, the codebook with definitions, the analytic memos, and an anonymised summary of participant characteristics can all be deposited. A reader can then evaluate your process even without the raw material, and the statement of restriction is itself informative. Openness was never all-or-nothing.

After this, you can

share the layer you can when the raw data is genuinely restricted.

The takeaway

Keep raw data untouched, do everything in recorded steps, and share the layers you legitimately can.

Easy to take the wrong way

That open science means publishing everything. Consent and law come first; what is shared is the process, wherever the data cannot follow.

Try this

Write a data dictionary for your main dataset — every variable, its meaning, its units, and how missing values are coded.