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 most dangerous documentation gap is the numeric missing code. Storing "declined to answer" as -99 or 999 is a landmine: if you forget to tell the software those aren't real numbers, they get averaged in, and a mean income drops by thousands. Prefer an empty cell (or NA). If you must use a code, record it in the codebook so that it is declared as missing before any analysis.
Below are six cryptic columns from a realistic export. For each, decide what it actually is, then read the codebook entry future-you needs, including the problem it hides.
📓 Build the Codebook
Six mystery columns, sample values shown. Classify each one correctly and its full codebook entry (including 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 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 a missing value that looks like a number. You can't recover any of that from the numbers alone, so it has to be written in the codebook.
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: without a codebook, a dataset can't be reused, shared, or reproduced, because only you know what it means. The codebook travels with the data, your validation rules are built from it, 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 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, not the instrument's in general. 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 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.