Field note
What should a handoff dictionary explain to a researcher or a receiving analyst?
Both need variable labels, units, value labels, missing-value reasons, population or universe, collection timing, methods, derivations, owners, and unresolved questions: enough context to interpret the dataset rather than merely parse it.
Document missingness deliberately
List every token that means absent and give each one its own meaning: not asked, refused, not applicable, skipped and genuinely unknown lead to different handling in an analysis. Say which absences are out of universe rather than missing data, because that distinction changes a denominator. Collapsing them into blank destroys information nobody downstream can reconstruct.
Keep method and meaning distinct
How a value was collected and what it means are different claims, and mixing them produces definitions nobody can act on. Put the concept, its scope and its exclusions in the definition; put the instrument, question wording or observation procedure in the source method; put formulas and the fields they draw on in the derivation. A reader can then tell whether a surprising value is a measurement decision or a definitional one.
Write for the receiving reader and freeze what you handed over
Write for somebody who receives the dataset without you: the universe, the collection period, the measurement basis, the value meanings, the owner, and the questions still open. Show where the documentation is thin instead of smoothing it over, because a document that looks uniformly finished is harder to trust. Freeze the edition you hand over so both sides can say which version the work was based on.
Worked example from the sample project
A research reader and a receiving analyst want overlapping things from the sample and emphasise them differently. The researcher reads condition and asks what the categories mean and how a not-rated tree should be treated in a model. The analyst reads tree_id and asks whether it is stable across field seasons and whether it can be joined on. Both questions are answered in a folio, and neither is answered by a schema.
The properties that carry the most weight for both are the ones that cost the most to write: the universe, the collection period, the measurement basis, the missing-value meanings and the unresolved questions. The sample leaves access_note visibly needs-review for exactly this reason. Showing the receiving reader where the documentation is still thin is more useful than handing them a document that looks finished everywhere.
Freeze the edition you hand over. A dictionary that keeps changing after the handoff leaves both readers unable to say which version their work was based on.
What this does not do
- The studio does not check any repository, journal or funder submission requirement.
- It performs no statistical, methodological or reproducibility review.
- A frozen edition is a point-in-time document, not a deposit or a registration.
Do this in the studio
Write for the person receiving the dataset, then freeze what you handed them.
- Open the Dataset context station and record purpose, universe, period, method and steward.
- Document missing states and value meanings before anything else in the folios.
- Freeze an edition at the Editions station and hand over that edition.
Open the studio at the Dataset context station