Шаблон README
Використовуйте цей шаблон для підготовки основного файлу документації для дослідницького набору даних. Заповнений README допомагає іншим користувачам зрозуміти, що містить набір даних, як організовані його файли, як дані були отримані та оброблені, а також як до них можна отримати доступ, інтерпретувати та повторно використовувати.
Інформація про ресурси
Тип ресурсу
Шаблон документації
Цільові користувачі
Дослідники, дослідницькі групи, куратори даних та розпорядники даних
Рекомендоване використання
Публікація набору даних, упаковка даних FAIR та депонування в репозиторії
Статус
Рекомендований шаблон Центру компетенцій
Завантажте шаблон README
Виберіть формат, який найзручніший для вашого робочого процесу. Markdown рекомендується для обчислювальних наборів даних, коду та машинозчитуваної документації. DOCX можна використовувати для підготовки та інституційного розгляду.
Завантажити Markdown Завантажити DOCX Переглянути PDF-файл з посиланням
Що таке README?
README – це основний файл документації, що постачається з дослідницьким набором даних. Він пояснює, що містить набір даних, як організовані його файли та папки, як дані були зібрані або створені, які кроки обробки були застосовані, а також як файли можна відкривати, інтерпретувати та повторно використовувати.
README доповнює метадані, введені в репозиторій. Він надає інформацію на рівні файлів, методологічну та практичну інформацію, яка може не поміститися в поля метаданих репозиторію.
Файл README та метадані репозиторію доповнюють один одного
Метадані репозиторію допомагають користувачам знаходити та ідентифікувати набір даних. Файл README допомагає їм розуміти та правильно використовувати його файли.
Що охоплює шаблон
Шаблон містить чотирнадцять розділів, організованих у чотири області практичної документації.
Ідентифікація набору даних та контекст
Назва набору даних, версія, автори, установи, відповідальна особа, дослідницька група, фінансування, наукова галузь, мета та пов'язані публікації.
Файли, структура та методи
Розмір набору даних, формати файлів, структура папок, опис основних файлів, методи збору або створення даних, обладнання, програмне забезпечення та обчислювальне середовище.
Відкриття, інтерпретація та повторне використання
Інструкції щодо відкриття та використання файлів, залежності програмного забезпечення, кроки обробки та аналізу, відомі обмеження, умови доступу, ліцензія та рекомендоване цитування.
Версії, права та підтримка
Персональні або конфіденційні дані, матеріали третіх сторін, історія версій, зміни, відповідальна контактна особа та додаткові примітки.
Як використовувати шаблон
1. Завантажити
Завантажте версію Markdown або DOCX.
2. Заповніть
Замініть текст інструкції інформацією про ваш набір даних.
3. Адаптувати
Збережіть відповідні розділи та позначте ті, що не застосовуються.
4. Перевірити
Перевірити узгодженість з метаданими, файлами та умовами доступу.
5. Включити
Помістіть заповнений файл README в кореневий каталог набору даних.
Рекомендоване ім'я файлу та розташування
Використовуйте чітку та зрозумілу назву файлу:
- README.md — рекомендовано для більшості пакетів даних FAIR;
- README.txt — підходить для документації у форматі звичайного тексту;
- README.pdf — може бути включено як додаткова версія з фіксованим макетом;
- README.docx — підходить як робоча версія, але менш зручний як єдиний формат збереження.
Приклад структури пакета
dataset-name/ │ ├── README.md ├── manifest.csv ├── metadata.json │ ├── data/ ├── scripts/ ├── documentation/ └── results/
Мінімальна інформація, яку потрібно включити
Як мінімум, файл README повинен ідентифікувати набір даних та його авторів, пояснити, що містять дані, описати основні файли та їх формати, вказати, як були отримані дані, надати інструкції щодо відкриття та інтерпретації файлів, а також вказати інформацію про доступ, ліцензію та контактну інформацію.
- Назва та версія набору даних
- Автори та контактна особа
- Короткий опис набору даних
- Структура файлів та папок
- Опис основних файлів
- Метод збору або створення даних
- Інструкції щодо програмного забезпечення та відкриття файлів
- Умови доступу та ліцензія
- Пов'язана публікація або проект
- Історія версій
Важливі примітки
- Не включайте паролі, облікові дані доступу або конфіденційну особисту інформацію до README.
- Не описуйте обмежену або конфіденційну інформацію детальніше, ніж дозволено чинною політикою доступу.
- Використовуйте ту саму назву набору даних, імена авторів, ідентифікатори, версію та ліцензію у README та метаданих репозиторію.
- Чітко розрізняйте необроблені дані, оброблені дані, скрипти, документацію та похідні результати.
- Вказуйте версії програмного забезпечення, залежності та файли конфігурації, коли вони необхідні для інтерпретації або відтворення даних.
- Оновлюйте README, коли змінюється структура набору даних, версія, умови доступу або вміст.