Codebooks & Documentation
A dataset without a codebook is a puzzle with the picture thrown away. Six months from now, grp, q3_rev, and a lone -99 will mean nothing to you, and the person most likely to reopen this file is future-you, who has forgotten everything. A codebook is the short document that keeps your data legible to that stranger.
What a codebook records
A codebook is a variable-by-variable dictionary, the place a construct's operational definition is written down for good. For every column it names:
- Name: the exact column header as it appears in the file.
- Label: a human-readable description ("Annual household income, USD").
- Type: continuous, ordinal, nominal, date, or identifier (this is the same idea as types of data, written down where the software can't guess wrong).
- Units / allowed values: kilograms; 1–5; the category set
{1 = control, 2 = drug A}. - Missing codes: how "no answer" is stored, ideally a blank rather than a number.
Naming conventions and the landmines
Good column names are short, lowercase, without spaces, and stable: age, income_usd, item3_rev. Cryptic names age badly, but the truly dangerous documentation gap is the numeric missing code. Storing "declined to answer" as -99 or 999 is a landmine: the day you forget to tell the software those aren't real numbers, they get averaged in, and a mean income drops by thousands. Prefer a genuinely blank cell (or NA); if you must use a code, the codebook is the one place that keeps it from detonating.
Below are six cryptic columns from a real-feeling export. For each, decide what it actually is, then read the codebook entry future-you needs, landmine and all.
📓 Build the Codebook
Six mystery columns, sample values shown. Classify each one correctly and its full codebook entry — with the ambiguity you'd regret in six months — gets written into the dictionary below.
Documented 0 / 6
📖 Your codebook
Classify a column above to start filling this in…
The pattern under the game: the values tell you the type, and the type tells you what could go wrong. A numeric-looking column can be a category (grp) or an identifier (pid) that must never be averaged; a Likert item may be reverse-worded; a bare date is ambiguous until you fix its format; and a stray -99 is missingness in disguise. None of that is recoverable from the numbers alone — it lives in the codebook or it's lost.
The six-months test: could a competent stranger — or you, next year — open this file and know exactly what every column means, which values are allowed, and how missing data is marked, without asking you? If not, the gap belongs in the codebook. Write it as you collect, not after.
Why it matters: the codebook is what makes a dataset reusable, shareable, and reproducible instead of a private riddle. It travels with the data, it's the reference your validation rules are built from, and it's the first thing a collaborator or reviewer will ask for. A tidy table plus a clear codebook is a dataset anyone can pick up and trust.
Common questions
How should I code missing values?
Leave the cell genuinely empty, or use a dedicated marker like NA — not a number. Numeric codes such as -99, 0, or 999 are dangerous because the software treats them as real data: forget to declare them and they get averaged straight into your means and SDs. Never use 0 in particular, since 0 is a legitimate value for many variables. If your software forces a numeric code, record it prominently in the codebook and convert it to missing as the very first cleaning step.
My variables come from a published questionnaire. Do I still need to document them?
You do, and citing the original paper is not enough on its own. The codebook has to let someone reproduce your scoring rather than the instrument's in general, so record the version or subscale you used, which raw items map to which scale, how you treated reverse-worded items, and how a total or mean was formed from them. Note anything you changed: a shortened form, a translated item, a response option you merged. If you dropped an item after a reliability check, that belongs there too. A reader holding the published questionnaire still cannot rebuild your dataset without knowing the choices you made on top of it.
What makes a good variable name?
Short, lowercase, no spaces or special characters, and stable over time — age, income_usd, item3_rev. Good names hint at the content and can encode useful flags (a _rev suffix for a reverse-scored item) without trying to be the codebook. Avoid names that are really values (a column called 2019), names that collide when truncated, and cryptic abbreviations only today-you understands. The codebook carries the full meaning; the name just has to be unambiguous and machine-friendly.