Developing a Codebook for Qualitative Research

A qualitative codebook lists every code in a study, and each entry gives the code's name, a definition, criteria for when to apply the code and when not to, and examples from the data. A team usually starts from deductive codes taken from a theory or the research questions, adds inductive codes found while reading, pilots the codebook on a few transcripts, and numbers each revision. With the version number recorded on each coding, a reader can see which version of the codebook coded which transcript.

In qualitative research, coding attaches short labels, called codes, to excerpts of interview transcripts, focus groups, field notes, or open-ended survey answers. A deductive code comes from a theory, earlier studies, or the interview guide before coding starts, and an inductive code comes from the data during coding. The two terms borrow the directions of deductive and inductive reasoning. Intercoder reliability measures how often two coders apply the same codes to the same excerpts. Writing about team coding at the Centers for Disease Control and Prevention, MacQueen and colleagues (1998) describe a structured codebook as a stable frame for the dynamic analysis of text. The codebook features MacQueen and colleagues describe were chosen to improve agreement among coders.

The sections below cover a codebook that a team of people applies in qualitative analysis. Writing Effective Annotation Guidelines covers label rules for annotation tasks that train or evaluate models, and Writing a Codebook an LLM Can Follow covers a codebook that a language model applies. Shared Codebook for Qualitative Coding documents Potato's codebook feature option by option.

Deductive, inductive, and hybrid codes

A deductive codebook is written before coding begins, and coding then shows how well the codebook's categories describe what participants said. An inductive codebook grows while you read. A passage that fits no code becomes a candidate code, and the candidate gets an entry once the idea recurs across participants. Thematic analysis and grounded theory both draw on inductive coding.

Many team projects combine the two directions. Fereday and Muir-Cochrane (2006) describe a hybrid process that integrated data-driven codes with theory-driven ones in a study of performance feedback in nursing. DeCuir-Gunby, Marshall, and McCulloch (2011) give steps for developing theory-driven and data-driven codes for interview data and for training other coders to apply the codebook. Roberts, Dowell, and Nie (2019) built a preliminary codebook from the research question, the literature, a survey from the same project, and a first scan of the interviews, then let unexpected themes enter during coding. In a hybrid codebook, each entry records the code's origin. A reader then sees which codes the study brought to the data and which codes the data produced.

The parts of a code entry

A code entry tells a coder who was not in the room when the code was invented how to apply the code. Roberts, Dowell, and Nie (2019) wrote each code with a label, a definition, a description, qualifications or exclusions, and examples from the raw data. The table below extends that form with an inclusion line, an atypical example, a counter-example, and the code's origin. The example is a deductive code from a study of teachers' experiences of remote teaching:

Exclusion criteria matter most where two codes sit close together, and an exclusion that names the neighboring code tells coders which of the two codes to choose. Take examples from your own transcripts, with identifying details removed. Invented examples leave out the digressions and half-finished sentences of real speech.

Parent and child codes

A long codebook is easier to apply as a tree. A parent code names a broad category, such as Workload, and child codes name the variants a study wants to count separately, such as after-hours contact with families. Each child code needs a separate entry. The parent's entry states whether coders apply the parent directly or only through a child, because a coder who applies both doubles the parent's count. In a hybrid codebook, an inductive code is often added as a child of a deductive parent. In the remote-teaching study, the pilot turned up passages about work spilling into home life, and the team added Home and work boundary as a child of Workload.

Piloting the codebook on a few transcripts

A pilot applies the draft codebook to a few transcripts before the main round of coding. Choose pilot transcripts that differ from each other (e.g., one participant from each site or group), and have two coders code every excerpt independently. Compare the two codings excerpt by excerpt, and decide for each disagreement whether the entry was unclear or the excerpt was ambiguous. An unclear entry gets a sharper definition, a new exclusion, or a new example.

After revising, code fresh transcripts rather than the pilot transcripts again. Entries written from the pilot transcripts fit those transcripts well, and recoding the same material shows little about how the codebook performs on new interviews. A coefficient computed on the pilot describes a draft codebook, and the reliability reported in a write-up comes from a later round. DeCuir-Gunby and colleagues discuss establishing reliability while training coders. Once the team agrees on a final version, the codebook changes only where coding cannot go on without a change. Roberts and colleagues recorded disagreements while testing their final version and followed the same rule.

Revising codes with a team

Team revisions include the following:

• Sharpen. Rewrite a definition or add an exclusion when coders read the entry differently.
• Add. Write an entry for an inductive code the data keeps producing.
• Merge. Fold two codes into one when coders cannot tell the two codes apart.
• Split. Divide a code that coders used for two different ideas.
• Retire. Remove a code that no one applied, or keep the code with a note when the absence of the code is a finding.

Have one person on the team edit the codebook, and have the rest of the team propose changes at a regular meeting instead of editing entries mid-transcript. Each decision gets a dated line in a change log with the change, the reason, and the people who agreed. A merge or a split changes what earlier codings mean, and the log names the excerpts the change touched.

Versioning the codebook

Give each version of the codebook a number and a date, such as 1.0 for the pilot draft and 2.0 for the codebook the main round uses, and keep every version. Record the version next to each transcript's coding. A methods section can then say which codebook coded which transcript. When a change alters what a code means, the transcripts coded under the earlier version are recoded for that code or reported as coded under the earlier definition. A change that fixes wording or adds an example needs no recoding. Publish the final version and the change log as an appendix or a supplementary file.

A codebook in Potato

Potato 2.13.1 stores a codebook in the project's database and records each change. The config below sets up the pilot round of the remote-teaching study. Both coders code every excerpt, coders can add a code while reading, and the user lead edits definitions and merges codes as adjudicator:

annotation_task_name: Remote teaching interviews
task_dir: .
output_annotation_dir: annotation_output/
data_files:
  - data/excerpts.jsonl
item_properties:
  id_key: id
  text_key: text
user_config:
  allow_all_users: true
  users: []
 
# Pilot round: both coders code every excerpt of the pilot transcripts
num_annotators_per_item: 2
 
# Coders may add a code while they read; only the lead edits definitions or merges codes
codebook_mode: extensible
 
adjudication:
  enabled: true
  adjudicator_users: [lead]
 
annotation_schemes:
  - annotation_type: multiselect
    name: codes
    description: Which codes apply to this excerpt?
    codebook: true
    labels:
      - name: Workload
        description: The teacher describes the time or effort that remote teaching took.
      - name: Student engagement
        description: The teacher describes whether students took part, paid attention, or completed work.
      - name: Technology access
        description: The teacher describes devices, internet connections, or software that students or the teacher had or lacked.
      - name: School support
        description: The teacher describes help, guidance, or resources from the school or district, or the lack of them.

codebook: true makes the scheme read codes from the codebook instead of the YAML. On the first server start, Potato seeds the codebook from labels, and each label's description becomes the code's short definition. From then on the database holds the codebook, and an edit to labels changes nothing. In the 2.13.1 browser interface, a coder can add a top-level code and edit the prose of an entry, and renaming, moving, and deleting a code go through the codebook API. For the main round, set codebook_mode: fixed and restart the server. In fixed mode, no one may add, rename, move, or delete a code, and an edit to a definition is queued as a proposal that an admin or adjudicator confirms or rejects.

Writing entries on the codebook page

On the /codebook page, each code's entry is a list of typed blocks. Paste an entry written in Markdown and choose the code, and Potato files each heading under the matching block:

### Short definition
 
The teacher describes the time or effort that remote teaching took.
 
### Use when
 
Hours, preparation, grading, or messages that took longer than in a classroom.
 
### Avoid when
 
Tiredness or stress with no task or time named.
 
### Examples
 
"The lesson plans took twice as long because everything had to work on a phone."
 
### Counter-examples
 
"I was exhausted all the time."

Use when holds the inclusion criteria and Avoid when the exclusion criteria. A ### Definition block holds the full definition, and a ### Rationale block can hold the code's origin. Potato has no separate block for atypical examples. Put atypical examples under Examples with a note. Coders see each code's short definition in the Codebook tray beside the excerpt.

Nested codes

The tray shows nested codes as a tree, and the 2.13.1 tray has no control for nesting a code. The codebook and qdpx exports of 2.13.1 list a codebook-backed scheme's codes at the top level, with the parent and color columns of codebook.csv left empty. A tree that has to leave Potato intact fits a hierarchical_multiselect scheme loaded from a CSV file, as described in Content Analysis. Coders then cannot edit codes during coding.

Adding codes between rounds

A deductive code added to labels after the first start reaches the codebook through the codebook CLI:

potato codebook config.yaml

The command creates a code for every YAML label the codebook lacks and copies only the name. Write the new code's definition on /codebook. Run the CLI only on a codebook the server has already seeded. On an empty codebook, the CLI creates the codes without the YAML descriptions, and the server then skips its seed. The potato codebook entry point of 2.13.1 drops the --dry-run flag and writes the codes. To preview without writing, run python -m potato.codebook_cli config.yaml --dry-run.

Revision numbers and change history

Adding, renaming, moving, merging, or deleting a code raises the codebook's revision number, and Potato stamps each saved annotation with the revision in effect. The tray's Review list shows each coder the excerpts the coder saved before a later revision. An edit to the prose of an entry leaves the revision number unchanged. The agreement page at /admin/iaa lists the codebook revisions under its agreement-over-time tables, as described in Agreement Drift and Re-Calibration Rounds.

In 2.13.1, a merge or a split made from the tray changes the codebook and leaves the codings already saved untouched. Excerpts coded with a merged code keep the old code's name in the annotation files. The team then recodes those excerpts or maps the old name to the new one during analysis, and records the decision in the change log.

The revision stamps stay in the project database and out of the annotation exports. To fix a codebook version for a methods section, export the codebook and take a snapshot at the end of each round:

python -m potato.export -c config.yaml -f codebook -o ./export/
potato snapshot create config.yaml --note "Codebook 2.0, after the pilot" --tag codebook-2.0

The export writes codebook.csv with each code's short definition and the number of times coders applied the code. The inclusion and exclusion criteria and the examples stay on /codebook and in the project database. The snapshot bundles the config, the data, the annotations, and the project database under the tag codebook-2.0. The snapshot's content hash covers the config, the data, and the annotations but not the database. A round that changed only the codebook therefore leaves the hash unchanged, and potato snapshot create saves that round only with --force. Project Snapshots covers the snapshot commands.

Frequently asked questions

What should a qualitative codebook include?

A qualitative codebook includes an entry for every code, with a name, a short and a full definition, inclusion and exclusion criteria, and typical, atypical, and counter-examples from the data. Many teams also record each code's origin and parent. The codebook as a whole has a version number, a date, and a change log.

Should a codebook use deductive or inductive codes?

Many team codebooks use both, starting from deductive codes taken from a theory, earlier studies, or the interview guide and adding inductive codes that the pilot transcripts produce. A purely deductive codebook suits a study that tests named categories, and a purely inductive codebook suits exploratory work such as grounded theory.

How do I keep an audit trail of codebook changes?

Keep an audit trail by numbering each codebook version, logging every change with the date, the reason, and the people who agreed, and recording which version coded each transcript. In Potato, each saved annotation records the codebook revision in effect, and potato snapshot create config.yaml --tag codebook-2.0 at the end of each round freezes the codebook with the annotations.

Further reading

• Shared Codebook for Qualitative Coding, for every codebook option in Potato
• QDA Mode, for one analyst coding a whole corpus with an open codebook, memos, and cases
• Intercoder Reliability in Qualitative Research
• Preparing Interview Transcripts for Qualitative Coding
• How to Use an LLM in Qualitative Coding and Report It
• Code Interview Transcripts With Two Coders and Report Alpha, for a codebook applied by two coders through to Krippendorff's alpha and a QDPX file
• Writing Effective Annotation Guidelines
• Writing a Codebook an LLM Can Follow
• Qualitative Data Analysis Software Compared
• Qualitative research in Potato

References

1. DeCuir-Gunby, J. T., Marshall, P. L., & McCulloch, A. W. (2011). Developing and Using a Codebook for the Analysis of Interview Data: An Example from a Professional Development Research Project. Field Methods, 23(2), 136-155. https://doi.org/10.1177/1525822X10388468
2. Fereday, J., & Muir-Cochrane, E. (2006). Demonstrating Rigor Using Thematic Analysis: A Hybrid Approach of Inductive and Deductive Coding and Theme Development. International Journal of Qualitative Methods, 5(1), 80-92. https://doi.org/10.1177/160940690600500107
3. MacQueen, K. M., McLellan, E., Kay, K., & Milstein, B. (1998). Codebook Development for Team-Based Qualitative Analysis. CAM Journal (Cultural Anthropology Methods), 10(2), 31-36. https://doi.org/10.1177/1525822X980100020301
4. Roberts, K., Dowell, A., & Nie, J.-B. (2019). Attempting rigour and replicability in thematic analysis of qualitative research data; a case study of codebook development. BMC Medical Research Methodology, 19, 66. https://doi.org/10.1186/s12874-019-0707-y
5. Jurgens, D., Chen, M., & Iyer, L. (2026). Potato 2.0: A Comprehensive Annotation Platform with AI-in-the-Loop Support. Proceedings of the 64th Annual Meeting of the Association for Computational Linguistics (Volume 3: System Demonstrations), 374-386. https://aclanthology.org/2026.acl-demo.37/