Разработка кодбука для качественного исследования

Качественный кодбук перечисляет все коды исследования, и запись каждого кода содержит его название, определение, критерии того, когда код применять и когда не применять, и примеры из данных. Обычно команда начинает с дедуктивных кодов, взятых из теории или исследовательских вопросов, добавляет индуктивные коды, найденные при чтении, опробует кодбук на нескольких расшифровках и нумерует каждую редакцию. Если номер версии записан при каждом кодировании, читатель видит, какая версия кодбука кодировала какую расшифровку.

В качественном исследовании кодирование присваивает фрагментам расшифровок интервью, фокус-групп, полевых заметок или ответов на открытые вопросы анкет короткие метки, которые называются кодами. Дедуктивный код берётся из теории, предыдущих исследований или гайда интервью до начала кодирования, а индуктивный код возникает из данных во время кодирования. Оба термина заимствуют направление дедуктивного и индуктивного рассуждения. Надёжность между кодировщиками измеряет, как часто два кодировщика применяют одни и те же коды к одним и тем же фрагментам. Описывая командное кодирование в Центрах по контролю и профилактике заболеваний США, MacQueen и соавторы (1998) называют структурированный кодбук устойчивой рамкой для динамического анализа текста. Особенности кодбука, которые описывают MacQueen и соавторы, были выбраны так, чтобы повысить согласованность кодировщиков.

Разделы ниже посвящены кодбуку, который применяет команда людей в качественном анализе. Руководство Как писать эффективные инструкции по разметке описывает правила меток для задач разметки, которые обучают или оценивают модели, а статья Как написать кодбук, которому может следовать LLM описывает кодбук, который применяет языковая модель. Страница Общий кодбук для качественного кодирования описывает функцию кодбука в Potato по каждому параметру.

Дедуктивные, индуктивные и смешанные коды

Дедуктивный кодбук пишется до начала кодирования, и кодирование затем показывает, насколько хорошо категории кодбука описывают то, что говорили участники. Индуктивный кодбук растёт по мере чтения. Отрывок, который не подходит ни под один код, становится кандидатом в коды, и кандидат получает запись, когда идея повторяется у нескольких участников. Тематический анализ и обоснованная теория опираются на индуктивное кодирование.

Многие командные проекты сочетают оба направления. Fereday и Muir-Cochrane (2006) описывают смешанный процесс, который объединил коды, выведенные из данных, с кодами, выведенными из теории, в исследовании обратной связи по результатам работы в сестринском деле. DeCuir-Gunby, Marshall и McCulloch (2011) дают шаги для разработки теоретических и эмпирических кодов для данных интервью и для обучения других кодировщиков применению кодбука. Roberts, Dowell и Nie (2019) составили предварительный кодбук на основе исследовательского вопроса, литературы, анкеты из того же проекта и первого просмотра интервью, а затем допускали появление неожиданных тем во время кодирования. В смешанном кодбуке каждая запись фиксирует происхождение кода. Читатель тогда видит, какие коды исследование принесло к данным, а какие коды породили сами данные.

Части записи кода

Запись кода объясняет кодировщику, которого не было в комнате, когда код придумали, как применять этот код. Roberts, Dowell и Nie (2019) описывали каждый код через метку, определение, описание, оговорки или исключения и примеры из исходных данных. Таблица ниже дополняет эту форму строкой включения, нетипичным примером, контрпримером и происхождением кода. Пример — дедуктивный код из исследования опыта учителей, работавших в дистанционном формате:

Критерии исключения важнее всего там, где два кода стоят близко друг к другу, и исключение, которое называет соседний код, подсказывает кодировщикам, какой из двух кодов выбрать. Берите примеры из собственных расшифровок, удалив идентифицирующие детали. В придуманных примерах нет отступлений и недоговорённых фраз живой речи.

Родительские и дочерние коды

Длинный кодбук удобнее применять в виде дерева. Родительский код называет широкую категорию, например Workload, а дочерние коды называют варианты, которые исследование хочет считать отдельно, например общение с семьями после рабочего дня. Каждому дочернему коду нужна отдельная запись. В записи родительского кода сказано, применяют ли кодировщики родительский код напрямую или только через дочерний, потому что кодировщик, который применяет оба, удваивает счёт родительского кода. В смешанном кодбуке индуктивный код часто добавляют как дочерний к дедуктивному родительскому. В исследовании дистанционного обучения пилотное кодирование выявило отрывки о том, как работа перетекает в домашнюю жизнь, и команда добавила Home and work boundary (граница между домом и работой) как дочерний код Workload.

Пилотное кодирование на нескольких расшифровках

Пилотное кодирование применяет черновой кодбук к нескольким расшифровкам до основного раунда кодирования. Выберите для пилота расшифровки, которые отличаются друг от друга (например, по одному участнику из каждой площадки или группы), и попросите двух кодировщиков независимо закодировать каждый фрагмент. Сравните два варианта кодирования фрагмент за фрагментом и для каждого расхождения решите, была ли неясной запись или неоднозначным сам фрагмент. Неясная запись получает более чёткое определение, новое исключение или новый пример.

После правки кодируйте новые расшифровки, а не пилотные повторно. Записи, написанные по пилотным расшифровкам, хорошо подходят именно к этим расшифровкам, и повторное кодирование того же материала мало что говорит о том, как кодбук работает на новых интервью. Коэффициент, вычисленный на пилоте, описывает черновой кодбук, а надёжность, о которой сообщают в публикации, берётся из более позднего раунда. DeCuir-Gunby и соавторы обсуждают установление надёжности в ходе обучения кодировщиков. Когда команда согласовала окончательную версию, кодбук меняется только там, где без изменения кодирование не может продолжаться. Roberts и соавторы фиксировали расхождения при проверке своей окончательной версии и следовали тому же правилу.

Командная правка кодов

Командная правка включает следующие действия:

• Уточнить. Перепишите определение или добавьте исключение, когда кодировщики понимают запись по-разному.
• Добавить. Напишите запись для индуктивного кода, который данные порождают снова и снова.
• Объединить. Слейте два кода в один, когда кодировщики не могут отличить эти два кода друг от друга.
• Разделить. Разбейте код, который кодировщики использовали для двух разных идей.
• Вывести из употребления. Удалите код, который никто не применял, или оставьте код с пометкой, когда само отсутствие кода является результатом.

Пусть кодбук редактирует один человек в команде, а остальные предлагают изменения на регулярной встрече, вместо того чтобы править записи посреди расшифровки. Каждое решение получает датированную строку в журнале изменений с самим изменением, причиной и теми, кто согласился. Объединение или разделение меняет смысл прежнего кодирования, и журнал называет фрагменты, которые затронуло изменение.

Версии кодбука

Дайте каждой версии кодбука номер и дату, например 1.0 для пилотного черновика и 2.0 для кодбука основного раунда, и сохраняйте все версии. Записывайте версию рядом с кодированием каждой расшифровки. Тогда раздел о методах может указать, какой кодбук кодировал какую расшифровку. Когда изменение меняет смысл кода, расшифровки, закодированные по прежней версии, перекодируются по этому коду или указываются как закодированные по прежнему определению. Изменение, которое исправляет формулировку или добавляет пример, не требует перекодирования. Опубликуйте окончательную версию и журнал изменений в приложении или в дополнительном файле.

Кодбук в Potato

Potato 2.13.1 хранит кодбук в базе данных проекта и записывает каждое изменение. Конфигурация ниже настраивает пилотный раунд исследования дистанционного обучения. Оба кодировщика кодируют каждый фрагмент, кодировщики могут добавить код во время чтения, а пользователь lead редактирует определения и объединяет коды как арбитр:

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 заставляет схему брать коды из кодбука, а не из YAML. При первом запуске сервера Potato заполняет кодбук из labels, и description каждой метки становится кратким определением кода. С этого момента кодбук хранится в базе данных, и правка labels ничего не меняет. В браузерном интерфейсе 2.13.1 кодировщик может добавить код верхнего уровня и отредактировать текст записи, а переименование, перемещение и удаление кода выполняются через API кодбука. Для основного раунда задайте codebook_mode: fixed и перезапустите сервер. В режиме fixed никто не может добавить, переименовать, переместить или удалить код, а правка определения встаёт в очередь как предложение, которое подтверждает или отклоняет администратор или арбитр.

Записи на странице кодбука

На странице /codebook запись каждого кода состоит из типизированных блоков. Вставьте запись, написанную в Markdown, выберите код, и Potato разнесёт каждый заголовок по соответствующему блоку:

### 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 содержит критерии включения, а Avoid when — критерии исключения. Блок ### Definition содержит полное определение, а блок ### Rationale может содержать происхождение кода. Отдельного блока для нетипичных примеров в Potato нет. Помещайте нетипичные примеры в Examples с пометкой. Кодировщики видят краткое определение каждого кода в боковой панели Codebook рядом с фрагментом.

Вложенные коды

Боковая панель показывает вложенные коды в виде дерева, но в боковой панели 2.13.1 нет элемента управления для вложения кода. Экспорты codebook и qdpx в 2.13.1 выводят коды схемы с кодбуком на верхнем уровне, а столбцы parent и color в codebook.csv остаются пустыми. Если дерево должно выйти из Potato целым, подойдёт схема hierarchical_multiselect, загруженная из CSV-файла, как описано в руководстве Контент-анализ. Кодировщики тогда не могут редактировать коды во время кодирования.

Добавление кодов между раундами

Дедуктивный код, добавленный в labels после первого запуска, попадает в кодбук через CLI кодбука:

potato codebook config.yaml

Команда создаёт код для каждой метки YAML, которой нет в кодбуке, и копирует только название. Определение нового кода напишите на /codebook. Запускайте CLI только на кодбуке, который сервер уже заполнил. На пустом кодбуке CLI создаёт коды без описаний из YAML, и сервер затем пропускает собственное начальное заполнение. Точка входа potato codebook в 2.13.1 отбрасывает флаг --dry-run и записывает коды. Чтобы посмотреть результат без записи, выполните python -m potato.codebook_cli config.yaml --dry-run.

Номера ревизий и история изменений

Добавление, переименование, перемещение, объединение или удаление кода увеличивает номер ревизии кодбука, и Potato помечает каждую сохранённую разметку ревизией, действовавшей в момент сохранения. Список Review в боковой панели показывает каждому кодировщику фрагменты, которые этот кодировщик сохранил до более поздней ревизии. Правка текста записи номер ревизии не меняет. Страница согласованности /admin/iaa перечисляет ревизии кодбука под таблицами согласованности по времени, как описано на странице Дрейф согласованности и раунды перекалибровки.

В 2.13.1 объединение или разделение из боковой панели меняет кодбук и не трогает уже сохранённое кодирование. Фрагменты, закодированные объединённым кодом, сохраняют в файлах разметки название старого кода. Затем команда перекодирует эти фрагменты или сопоставляет старое название с новым при анализе и записывает решение в журнал изменений.

Метки ревизий хранятся в базе данных проекта и не попадают в экспорт разметки. Чтобы зафиксировать версию кодбука для раздела о методах, в конце каждого раунда экспортируйте кодбук и создайте снимок:

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

Экспорт записывает codebook.csv с кратким определением каждого кода и числом применений кода кодировщиками. Критерии включения и исключения и примеры остаются на /codebook и в базе данных проекта. Снимок упаковывает конфигурацию, данные, разметку и базу данных проекта под тегом codebook-2.0. Хеш содержимого снимка охватывает конфигурацию, данные и разметку, но не базу данных. Поэтому раунд, в котором изменился только кодбук, не меняет хеш, и potato snapshot create сохраняет такой раунд только с --force. Страница Снимки проекта описывает команды снимков.

Частые вопросы

Что должен включать качественный кодбук?

Качественный кодбук включает запись для каждого кода с названием, кратким и полным определением, критериями включения и исключения, а также типичными и нетипичными примерами и контрпримерами из данных. Многие команды также записывают происхождение и родительский код каждого кода. У кодбука в целом есть номер версии, дата и журнал изменений.

Использовать ли в кодбуке дедуктивные или индуктивные коды?

Многие командные кодбуки используют и те и другие: начинают с дедуктивных кодов, взятых из теории, предыдущих исследований или гайда интервью, и добавляют индуктивные коды, которые порождают пилотные расшифровки. Чисто дедуктивный кодбук подходит исследованию, которое проверяет заранее названные категории, а чисто индуктивный кодбук подходит поисковой работе, например в обоснованной теории.

Как вести журнал аудита изменений кодбука?

Журнал аудита ведут так: нумеруют каждую версию кодбука, записывают каждое изменение с датой, причиной и теми, кто согласился, и отмечают, какая версия кодировала каждую расшифровку. В Potato каждая сохранённая разметка записывает действующую ревизию кодбука, а potato snapshot create config.yaml --tag codebook-2.0 в конце каждого раунда замораживает кодбук вместе с разметкой.

Дополнительное чтение

• Общий кодбук для качественного кодирования — все параметры кодбука в Potato
• QDA Mode — для одного аналитика, который кодирует весь корпус с открытым кодбуком, заметками и кейсами
• Надёжность между кодировщиками в качественных исследованиях
• Подготовка расшифровок интервью к качественному кодированию
• Как использовать LLM в качественном кодировании и сообщать об этом
• Кодирование расшифровок интервью двумя кодировщиками и отчёт об альфе — кодбук, который два кодировщика применяют вплоть до альфы Криппендорфа и файла QDPX
• Как писать эффективные инструкции по разметке
• Как написать кодбук, которому может следовать LLM
• Сравнение программ для качественного анализа данных
• Качественные исследования в Potato

Литература

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/