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

Короткий текстовый файл README решает эту проблему. Это инструкция к набору данных: он объясняет, какие файлы входят в пакет, откуда взялись числа, в каких единицах записаны значения и как интерпретировать пропуски. Ниже — полностью вымышленный учебный пример из четырёх файлов и готовый README, который можно скопировать и адаптировать под свой проект.

Что такое README и чем он отличается от словаря переменных

README — это описание всего пакета данных. Он сообщает:

  • сколько файлов в наборе и зачем нужен каждый;
  • как файлы связаны между собой;
  • откуда взяты данные;
  • какие единицы измерения и обозначения пропусков используются;
  • какие проверки были выполнены.

В нашем пакете определения id и hours вынесены в отдельный codebook.txt: это выбранная структура примера. Определения можно включить и непосредственно в README, если они согласованы с данными. Как описывать названия, значения и коды, показано в статье о кодировочной книге анкеты.

Пример набора из четырёх учебных файлов

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

Имя файлаНазначение
README.txtОписание всего набора (этот документ)
study_time.csvТаблица с данными об учебном времени четырёх условных участников
codebook.txtСловарь переменных: описание полей id и hours
processing.txtПорядок обработки данных: проверки и правила
Учебный пакет из README.txt, study_time.csv, codebook.txt и processing.txt. Табличный файл: 4 строки, 2 поля, 3 известных значения часов и 1 пропуск.
Учебная схема, данные вымышлены. README описывает пакет, codebook — переменные. В часах 1, 2, пропуск и 0 ноль не является пропуском.

Единственная таблица — study_time.csv. Вот её полное содержимое:

idhours
P011
P022
P03
P040

Четыре строки данных, два столбца. Значения hours: 1, 2, пропуск (пустая ячейка), 0.

В вымышленной строке P04 значение hours равно 0: это известное условное число часов. В строке P03 значение отсутствует. Из этих учебных значений нельзя делать выводы о поведении реальных участников.

В таблице пустая ячейка P03 означает отсутствие hours. В двухколоночном CSV строка имеет вид P03,: после запятой-разделителя значение последнего поля отсутствует. В README этот способ записи нужно объяснить явно.

Готовый README: полный текст для копирования

Ниже — законченный учебный README. Он составлен по образцу рекомендаций Корнеллского университета (Cornell Data Services, раздел «Recommended content») и Гарвардской медицинской школы (Harvard Medical School Biomedical Data Management, раздел «What is a README File?»). Полные ссылки на эти руководства — в конце статьи. Вы можете взять этот текст за основу и заменить вымышленные детали на свои.

НАЗНАЧЕНИЕ
Этот README описывает вымышленный учебный пакет. Все ID и значения
условные. Реального сбора данных, опросов и измерений не было.

СОСТАВ ФАЙЛОВ
README.txt — описание пакета.
study_time.csv — единственный табличный файл.
codebook.txt — описание полей id, hours и обозначения пропуска.
processing.txt — предлагаемый порядок проверки учебной таблицы.

ПРОИСХОЖДЕНИЕ И ВЕРСИЯ
Учебный пример подготовлен 2026-10-26. Это не дата реального сбора.
Версия учебного пакета: v1.

ФОРМАТ И ЕДИНИЦЫ
study_time.csv: UTF-8, разделитель полей — запятая, первая строка — заголовок.
4 строки данных, 2 поля: id и hours.
id — условный текстовый ID: P01, P02, P03, P04.
hours — целое неотрицательное число часов самостоятельной работы.
Определения полей и выбранные обозначения записаны в codebook.txt.

ПРОПУСКИ
В строке P03 значение hours отсутствует. Строка CSV имеет вид P03,
с пустым последним полем после запятой-разделителя.
В строке P04 значение hours равно 0. Это известное условное значение.
Причина отсутствия hours у P03 в учебном наборе не задана.

ПРОВЕРКИ УЧЕБНОЙ ТАБЛИЦЫ
Проверены 4 уникальных ID: P01, P02, P03, P04.
Известные значения hours: 1, 2, 0 — всего 3.
Один пропуск: hours у P03. Отрицательных известных значений нет.
Исходных строк 4, столбцов 2; заголовок не входит в число строк данных.

ОГРАНИЧЕНИЯ И КОНТАКТ
Из четырёх вымышленных строк не делают выводов о реальных студентах.
Реальный контакт ответственного в этом примере не указан.
Лицензия и условия использования реальных данных здесь не задаются.
Для своего набора укажите фактические условия доступа и контакт.

Обратите внимание на раздел «Проверки»: в нём указаны точные количества — 4 ID, 4 строки, 2 поля, 3 непустых hours, 1 пропуск. Если бы я писал этот README для реального набора, я перечислил бы конкретные проверки, которые провёл, а не придумывал опросы.

Чек-лист: что проверить перед передачей пакета

Когда готовите свой набор к отправке коллеге или научному руководителю, пройдите по этому короткому списку:

  • Файлы: все ли файлы, упомянутые в README, лежат в папке? Нет ли лишних?
  • Числа: совпадает ли количество строк в таблицах с заявленным в README?
  • Пропуски: одинаково ли обозначены пропуски во всех файлах (пустая ячейка, NA или другой код)?
  • Ноль: не спутан ли ноль с пропуском? Если 0 — осмысленное значение, напишите об этом в README.
  • Кодировка: соответствует ли указанная в README кодировка реальному файлу и правильно ли читается кириллица? Для нашего учебного CSV выбран UTF-8; это не утверждение о кодировке всех наборов данных.
  • Версия: если вы меняли файлы, указан ли номер версии и что именно изменилось?

Распространённые ошибки

  1. Описание переменных не найдено. В нашем пакете значения полей вынесены в codebook.txt, а README указывает на него. Можно описать переменные и непосредственно в README; важно, чтобы читатель знал, где находятся определения и чтобы они согласовывались с файлами.
  2. Ноль смешан с пропуском. В hours этого примера 0 — известное значение, а пустое поле — отсутствие значения. Для собственного набора выберите и опишите правило пропусков, затем проверьте, как его распознаёт используемая программа. Специальный код нельзя включать в обычные расчёты как число часов.
  3. Пропуск без пояснения. Опишите обозначение отсутствующих значений. Если причина отсутствия известна из документации, укажите её; если нет, напишите «не установлена». По одной пустой ячейке нельзя решить, был ли отказ от ответа или техническая ошибка. В нашем примере причина не задана.
  4. Формат не согласован с задачей передачи. Оба упомянутых руководства рекомендуют plain text или Markdown и советуют избегать проприетарных форматов, когда это возможно. Это рекомендации источников, а не обязательный формат для всех проектов.
  5. Нет контакта. В реальном пакете укажите, к кому обращаться с вопросами. В учебном примере контакт не указан намеренно, не выдумывайте.

Использованные источники

README в этой статье составлен по образцу следующих рекомендаций:

Границы: что README не делает

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

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

Что дальше

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

Источники

Фото: Nataliya Vaitkevich / Pexels