How to write a codebook (data dictionary) for your research data

← All writing

Every dataset has a codebook, whether or not anyone wrote it down. It's the knowledge that q7_r is the reverse-coded version of question 7, that 99 means "refused," that income is in thousands, and that the 2023 wave dropped two answer options. If that knowledge lives only in your head, the dataset stops being usable the day you move on, and a surprising number of times, "the day you move on" turns out to be next semester.

This guide covers what a codebook is, what goes in one, a template you can copy, and how to build one without starting from a blank page.

Codebook, data dictionary: what's the difference?

In practice, not much. Codebook is the older term from survey research, and it often includes the full question wording and response frequencies. Data dictionary is more common in databases, health research, and administrative data, and it's usually a table: one row per variable, one column per attribute. Funders and repositories use both words and mean the same thing: a document that tells a stranger what every variable in your data means.

Pick whichever term your field uses. The rest of this guide says "codebook" for short.

Why it's worth the hour

• Your own analysis. Most coding mistakes in cleaned data come from a misremembered value: treating 99 as a real age, or forgetting a variable was reversed. A codebook is where you check.
• Your co-authors and students. Anyone who joins the project can start working without a two-hour walkthrough.
• Your data management plan. Most DMPs promise documentation. The codebook is the documentation. The DMP guide shows how to describe it.
• Sharing and reuse. Repositories ask for one, and a dataset without it is close to unusable. It's one of the main things that makes data reusable under the FAIR principles.

What goes in a codebook

A good codebook has two parts: a short description of the dataset as a whole, and a variable-by-variable listing.

About the dataset

• Title, creators, and a contact.
• What the data are: the population or units, the time period, how the data were collected, and the sample size.
• Which file (or files) the codebook describes, with the version or date.
• How the files relate to each other, if there's more than one, and which variable links them (a student ID, a site code).
• Any weights, and when to use them.
• Conventions used throughout: how missing values are coded, date formats, units.

For each variable

• Name, exactly as it appears in the file.
• Label: a short, plain description ("Age at enrollment, in years").
• Type: numeric, text, date, categorical.
• Values: for categories, every code and what it means (1 = Strongly disagree ... 5 = Strongly agree). For numbers, the unit and the valid range.
• Missing values: each missing code and why it's missing. "Refused," "Don't know," "Not asked (skip pattern)," and "Not applicable" are different things, and an analyst needs to tell them apart.
• Source: the question wording for survey items, the original field for administrative data, or the formula for anything you computed.
• Notes: recodes, top-coding, changes between waves, known problems.

That "source" column is the one people leave out, and it's often the most useful. "Satisfaction" means very little until you know whether respondents were asked about their course, their advisor, or the whole institution.

A template you can copy

For most projects a spreadsheet is enough. Here's the layout, with two sample rows:

Save it as CSV next to the data (and as a PDF too, if people will print it). Put the dataset-level description at the top of your README, or in a short first tab, and point to it from the codebook. The guide to writing a dataset README covers what it should say, and the guide to organizing research data shows where it lives.

Don't start from a blank page

Statistical software already knows most of what goes in a codebook, as long as you've set variable and value labels. Generate a draft, then add what the software can't know: sources, reasons for missingness, and notes.

• Stata: codebook and describe print names, labels, types, ranges, and value labels. labelbook lists every value label set.
• SPSS: the Display Dictionary command (or File > Display Data File Information) exports variable and value labels.
• R: packages such as codebook and labelled build a codebook from labelled data, and skimr gives quick summaries you can paste in.
• REDCap and Qualtrics: both export a data dictionary or survey file with question text and response codes. That's a strong start for survey projects.

If your data came from a spreadsheet with no labels at all, write the codebook first and apply labels from it. It's faster than it sounds, and your cleaning code gets shorter.

Mistakes that make a codebook useless

• It describes a different version. The codebook says 42 variables; the file has 47. Update the codebook in the same step as the data, and date both. The reproducibility guide has a simple way to tie them together.
• Labels that repeat the name. "SAT_ADV: sat adv" tells nobody anything.
• One code for every kind of missing. If "didn't answer" and "wasn't asked" are both blank, nobody can compute a response rate or check a skip pattern.
• Derived variables with no formula. "GPA_adj" needs the rule that made it, or the code file that did.
• Locked in a proprietary format. A codebook that only opens in one program shares the same fate as data that only opens in one program.
• Private details in the examples. Frequency tables of small groups, or open-text answers pasted in as "examples," can identify people. The data ethics guide covers what to watch for.

When you deposit the data

Upload the codebook as a separate file alongside the data, not buried in a zip. Mention it in the repository description, and name it in your data availability statement if part of the data is restricted: the codebook can almost always be public even when the data can't, and it lets people judge whether it's worth applying for access. Some social science archives, ICPSR among them, will prepare a formal codebook in the DDI metadata standard when you deposit, but they'll still ask for your documentation to start from. The repository guide covers where to deposit.

If you support researchers

Codebooks are a good hands-on workshop: people bring their own data, generate a draft in their software, and leave with something finished. It pairs well with a DMP or data organization session. If your campus is building that kind of support, the guide to starting research data services is a place to begin, and I help institutions set it up. Get in touch if that would help.

Common questions

Is a codebook the same as a data dictionary? For most purposes, yes. Codebook is the traditional survey research term and often includes question wording and frequencies; data dictionary is more common for databases and administrative data. Both describe every variable so someone else can use the data correctly.

What format should a codebook be in? An open format such as CSV or a spreadsheet saved as CSV, plus a PDF if people will read it on paper. Avoid formats that only open in one statistics package.

Do I need a codebook for qualitative data? You need documentation, though it looks different: a list of files, participant attributes and how they're coded, the interview guide, and your coding scheme with definitions. The coding scheme is often called a codebook in qualitative work too.

Can software make the codebook for me? It can make a good draft. Stata, SPSS, R, REDCap, and Qualtrics can all export names, labels, and codes. You still need to add sources, missing-value reasons, and notes on how variables were derived.