README к набору данных: обязательные разделы

README — первое, что открывает человек, скачавший набор. От него зависит, поймёт ли читатель, что внутри, и сможет ли он использовать данные без переписки с автором.

Хороший README занимает одну-две страницы и отвечает на вопросы в порядке их возникновения.

Назначение и контекст

Начните с одного абзаца: что это за данные, для какого исследования собраны, кто автор.

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

Структура файлов

Перечислите файлы и папки с коротким описанием: data.csv — основной набор, codebook.md — описание переменных, scripts/ — код обработки.

Если файлов много, добавьте таблицу. Читатель должен найти нужное за минуту, а не исследовать архив.

Методы сбора

Опишите, как получены данные: опрос, измерение, выгрузка из системы, компиляция из открытых источников.

Укажите инструменты и приборы, если они влияют на значения. Для опросов — способ распространения и размер выборки.

Обработка и преобразования

Перечислите шаги обработки: удаление дублей, перекодировка, расчёт производных переменных.

Ссылайтесь на скрипты, если они приложены. Отсутствие описания обработки делает данные менее пригодными для повторного анализа.

Пропуски и ограничения

Отдельный раздел о том, чего в данных нет: какие группы не представлены, какие вопросы не задавались, какие значения исключены.

Честное описание ограничений повышает доверие и снижает риск неверного использования.

Лицензия и права

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

Права на персональные данные не передаются лицензией: об этом стоит сказать прямо.

Доступ и условия

Если данные открыты, напишите об этом. Если доступ ограничен, опишите процедуру запроса и критерии.

Не ограничивайтесь фразой «по запросу»: укажите, кому и как писать.

Цитирование

Приведите готовую строку цитирования и DOI. Это повышает шанс, что набор процитируют правильно.

Укажите, как ссылаться на версию: на конкретную или на концептуальную.

Контакты и поддержка

Один контакт для вопросов по данным. Если авторов несколько, назначьте ответственного.

Укажите, как сообщать об ошибках: это помогает исправлять набор, а не только обсуждать его.

Версии и изменения

Раздел с историей: что изменилось от версии к версии. Даже небольшие правки стоит фиксировать.

Если ошибка была исправлена, опишите её — пользователи старых версий должны знать о проблеме.

Частые ошибки

README отсутствует;
описание без структуры файлов;
нет лицензии;
отсутствие контакта;
описание методов в общих словах;
нет истории версий;
README устарел относительно данных.

Как проверить README

Дайте файл коллеге, не участвовавшему в проекте, и попросите найти конкретную переменную. Если он справился за минуту, структура работает.

Отметьте места, где он задавал вопросы: их стоит переписать.

README и машинная обработка

Часть репозиториев читает метаданные автоматически, но README остаётся для людей. Не пытайтесь заменить им машиночитаемое описание.

Чего не хватает чаще всего

Контакта, лицензии и описания структуры. Эти три пункта закрывают большинство вопросов пользователей.

Если README пишется в спешке, начните именно с них.

Пример структуры

Короткий блок «Что внутри», таблица файлов, раздел «Как использовать», лицензия, цитирование, контакт.

Такой порядок соответствует вопросам читателя: сначала «что это», затем «как применить».

Как описать ограничения использования

Прямо скажите, для каких задач данные не подходят: например, нельзя переносить выводы на другие регионы или периоды.

Это защищает и автора, и читателя от неверного применения.

Как поддерживать актуальность

Обновляйте README при каждом релизе: добавление файла или переменной должно отражаться в описании.

Устаревший README хуже отсутствующего: он создаёт ложное впечатление о наборе.

Как оформить README технически

Используйте Markdown: заголовки, списки, таблицы. Такой файл читается и на сайте репозитория, и в текстовом редакторе.

Не вставляйте изображения без описания: они не несут информации для тех, кто читает текст.

Итог: минимальный рабочий README

Один абзац о наборе, таблица файлов, методы, ограничения, лицензия, цитирование, контакт.

Этого достаточно, чтобы набором можно было пользоваться без переписки, а остальное добавляется по мере необходимости.

Что писать в разделе «Как использовать»

Короткий пример: какой файл открыть, какая переменная ключевая, какие фильтры применить.

Один пример из трёх строк экономит читателю больше, чем абзац общих указаний.

Чек-лист

Назначение описано.
Структура файлов перечислена.
Методы сбора указаны.
Обработка описана.
Ограничения сформулированы.
Лицензия и доступ указаны.
Строка цитирования приведена.
Контакт есть.

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

Сколько должен занимать README?

Обычно одну-две страницы. Если материала больше, вынесите детали в отдельные документы и дайте ссылки.

Нужен ли README, если есть статья?

Да. Статья описывает исследование, README — конкретный набор файлов.

На каком языке писать README?

На языке публикации, при необходимости — с английской версией. Для международных наборов английский предпочтителен.

Можно ли менять README после публикации?

Да, если это не меняет смысл данных. Существенные изменения фиксируйте в истории версий.