How to Write a Survey Data Codebook? Variables, Options, Missing Values, and Derived Rules

To judge whether a codebook is adequate, a more reliable approach than checking whether all fields are filled is to ask the original questionnaire designer to leave the meeting room and let another analyst independently reproduce a metric from the report using only the data file and codebook. If that analyst cannot determine the denominator, mistakes “not shown” for “dissatisfied,” or cannot tell how a composite score was generated, the codebook still relies on the tacit knowledge retained in the original author's mind.

Therefore, a codebook is not just a bilingual table accompanying an exported spreadsheet; it is a versioned contract among questionnaire semantics, data structure, and analysis scope. It must make clear both what a variable represents to humans and which values are valid, which records are applicable, and how derived results can be recalculated from raw fields. When there are many questions, it is not necessary to adopt complex metadata standards from the outset, but these three layers of relationships cannot be missing.

Why a Dataset with Only Six Variables Can Still Be Misread

Suppose a feature experience survey exports the following variables: respondent_id, used_feature, sat_feature, reason_1, reason_2, and sat_top2. Merely looking at the names, an analyst still cannot determine whether satisfaction was measured on a five-point or ten-point scale, whether zeros in multiple-choice items mean “not selected” or “not seen,” whether the composite indicator includes “don’t know,” nor is it clear that feature satisfaction was shown only to actual users.

A usable variable-level codebook should explain these six variables at least as follows:

The most important point here is not what the table looks like but that each field simultaneously answers four questions: where it comes from, who had the opportunity to produce a value, what each value means, and how it may be used in analysis. The ICPSR description of codebooks also emphasizes that a codebook describes the content, structure, and layout of the data collection, with variable-level information including variable names, labels, full question text, actual values, and value labels; the meaning of missing data also needs to be recorded.

A Codebook Needs Study-Level, File-Level, and Variable-Level Information

Study-level information explains why the data were generated: research objectives, target population, collection period, mode, sampling and recruitment methods, questionnaire language, consent and access conditions, responsible parties, and suggested citation. Without this layer, even accurately defined variables may be extrapolated to the wrong population or time period.

File-level information explains what the files at hand represent: whether a row corresponds to a respondent, a response, or an event; the primary and foreign keys; whether the file contains raw, cleaned, or public de-identified data; character encoding, date and time zones, wide or long table structure; and which questionnaire and processing script version it corresponds to. In multi-wave tracking or combined survey and interview settings, it is also necessary to specify how files link to one another.

Variable-level information is what most people recognize as the data dictionary: stable variable names, short labels, full question text and prompts, question version, data type, unit, reference period, response codes, scale orientation, target population, skip logic, special missing values, cleaning rules, and derivation formulas. The DDI-Codebook standard from the DDI Alliance places studies, data files, variables, and questions in one descriptive framework, also covering provenance, processing, quality control, access, and related materials. This shows that a codebook is not an isolated “column description,” but part of data provenance and processing history.

Teams do not necessarily need to produce DDI XML right away, but they can borrow from its hierarchical thinking: first establish study and file context, then explain each variable. Otherwise, a table with hundreds of columns can be very detailed yet still fail to answer “whom do these data represent?”

Missing Values Should Not Be Represented by a Single Blank

Blanks in survey data can arise from at least four processes: respondents never saw the question due to skip logic; saw it but skipped or refused; chose “don’t know”; or dropped out mid-response. Another type of missing results from post-processing, e.g., invalid raw values being set to blank. These correspond to different denominators and different risks of bias, so collapsing them into one blank makes recovery difficult.

Using the feature satisfaction example above: those who did not use the feature are structurally not applicable and cannot be included in the satisfaction denominator; users who saw the question but refused are item missing, and the extent of missingness should be reported; those who dropped out before reaching the question constitute unit non-completion, which may signal attrition bias. If public files suppress small groups for privacy reasons, another code should be used so analysts do not mistake disclosure control for no record.

In practice, one can reserve negative codes for special statuses, or retain raw blanks and add a separate missing-reason field. Which approach is chosen is not what matters; what matters is that raw data, codebook, and analysis scripts use the same rules. Do not let “refused = -7” suddenly become “logic not shown” in the next project, and do not include special missing values in mean calculations.

Multiple Choice, Randomization, Weights, and Derived Variables Must Be Documented to the Point of Reproducibility

Multiple-choice questions are typically split into multiple binary variables or stored in a “respondent–option” long table. The codebook must specify the storage format, whether the number of choices was limited, whether options were randomized, the difference between zero and blank, and where “other” text is stored. If an option is added mid-survey, it must be marked from which version it was visible so that earlier samples’ “not shown” is not treated as “not selected.”

Randomization and version branching should preserve random group, display order, wording version, and experimental unit. Keeping only the final answer mixes order effects and different wordings. Even if these fields are not used in standard reports, they remain necessary metadata for interpreting anomalies in comparisons and replicating experiments.

Weight variables should not be labeled simply as “final weight.” At minimum, document the target distribution, variables used in calibration, trimming or scaling, applicable population, weight mean and range, and which script version generated them. If different analyses use different weights, name them separately and specify their purposes. Weights can adjust imbalances in known dimensions, but they cannot automatically fix unknown coverage and nonresponse bias.

Derived variables must retain source variables, filtering conditions, formulas, special missing handling, rounding rules, and version. For example, “share of satisfied users” should be written as the number of respondents with Q4 equal to 4 or 5 divided by the number of valid responses to Q4; not just “computed from satisfaction.” For complex indicators, attach executable code or pseudocode, and use several known inputs and outputs as unit tests.

Variable Names Should Be Stable, but When Meaning Changes, Do Not Pretend Continuity

Using q12 as a variable name facilitates reference to the page but drifts with inserted items, deleted items, and multilingual versions. A more robust name can express the construct and reference period, e.g., feature_use_30d or feature_sat_5pt. Question numbers are kept in a separate “questionnaire position” field, while the variable name is used for cross-version tracking.

Stability does not imply reusing the same variable forever. A change matrix can help decide:

• If only typo or display style changes and measurement meaning is unchanged: keep the variable name and add a display version.
• If the reference period changes from 30 days to 90 days, or the scale changes from five to seven points: create a new variable and note that they cannot be directly concatenated.
• If options are added but the core question remains the same: keep the main question version while recording the starting version for each option’s availability.
• If derived formulas or weighting methods change: preserve the old results, create a new version noting the scope of recalculation, and do not overwrite historical definitions.

The codebook itself also needs a version number, last updated timestamp, maintainer, and change log. Generate an initial version when the questionnaire is released, update it after pretesting, freeze question and code mappings when official data collection begins, and add processing notes during cleaning and derivation. Making the codebook evolve with the data is far more reliable than reconstructing the documentation from memory after the project ends.

Validate by “Blind Handover,” Not by the Number of Fields Completed

Before delivery, ask a colleague who did not participate in the questionnaire design to complete five tasks relying solely on the data, codebook, and specified scripts:

1. State what each row represents and find a stable primary key;
2. Calculate the valid denominator for feature satisfaction and explain why non-users are excluded;
3. Distinguish between “not selected” and “not shown” in multiple-choice variables;
4. Recalculate a derived indicator from raw variables and match the delivered result;
5. Identify the questionnaire version, collection period, and the population to which this file can be extrapolated.

If any step requires a verbal inquiry to the original author, feed the answer back into the codebook or related materials. If two analysts obtain different bases, do not dispute which graph is correct first; find the missing rule in the contract. The real acceptance criterion is independent interpretation and recalculation, not how many columns were filled.

In questionnaire-based workflows, question text, options, display logic, and collection batches can serve as the initial source for the codebook. The team must additionally capture research population, business definitions, cleaning decisions, derived formulas, and version responsibilities. Tools can export fields, but they cannot decide for the team whether “don’t know” is a valid response, nor can they assess whether a scale change breaks continuity. It is these decisions that, when recorded, prevent data from losing meaning soon after leaving the original author.

Sources for Codebook Standards

• ICPSR: What is a codebook?
• DDI Alliance: DDI-Codebook 2.6