Pliki README
Pliki README to prosty sposób na stworzenie dokumentacji zbioru danych:
- dzięki plikom README dane stają się zrozumiałe i użyteczne,
- zawierają informacje o kontekście danych, o tym, z którym projektem badawczym są powiązane, oraz o tym, jak należy je interpretować,
- pozwalają zrozumieć, w jaki sposób zbiór danych wiąże się z innymi zbiorami danych.
Plik README ma na celu umożliwienie prawidłowej interpretacji danych – zarówno przez twórcę/producenta danych (np. po paru latach od czasu zebrania danych), jak i przez inne osoby w przypadku udostępnienia danych. Do opisu danych preferowane są metadane oparte na międzynarodowych standardach, jednak nie zawsze te ustandaryzowane informacje są wystarczające, żeby zrozumieć dane, wtedy właściwym rozwiązaniem jest przygotowanie pliku README.
Dobre praktyki
-
Liczba plików README
W wielu przypadkach właściwym rozwiązaniem będzie utworzenie jednego pliku README dla zestawu danych zawierającego pliki np. o podobnym formacie lub grupy plików, które są logicznie pogrupowane pod kątem użytkowania. Jednak czasami sensowne może być utworzenie pliku README dla pojedynczego pliku danych.
-
Tytułowanie plików README
Plik README najlepiej nazwać tak, aby można go było łatwo powiązać z plikiem lub plikami danych, do których się odnosi. Jeśli plik README jest przypisany do większej liczby plików, można dodać przedrostek „00_” przed nazwą pliku README (np. „00_README.txt”), co spowoduje, że plik pojawi się na górze listy plików.
-
Format zapisu plików README
Dokument README powinien zostać zapisany w formacie otwartym, np. txt (popularne rozszerzenie pliku Notatnika, bezpłatnej aplikacji dla systemu Windows). Powinno się unikać formatów komercyjnych, takich jak MS Word.
-
Formatowanie tekstu w plikach README
Plik README powinien być łatwy do zrozumienia. W tym celu można np. oddzielić ważne informacje pustymi wierszami, zamiast umieszczać je wszystkie w jednym długim akapicie.
Wiele plików README należy identycznie sformatować. Informacje należy przedstawiać w tej samej kolejności, przy użyciu podobnej terminologii.
-
Format daty i czasu używany w plikach README
Należy stosować standardowy format daty i czasu. Sugerowany format: standard daty W3C/ISO 8601, który określa międzynarodowy standard zapisu w formacie RRRR-MM-DD lub RRRR-MM-DDThh:mm:ss (niezbędne do prowadzenia rejestrów lub precyzyjnego określenia czasu zdarzeń, np. 2026-05-05T14:30:00).
-
Taksonomie i słowniki używane w plikach README
Należy przestrzegać konwencji naukowych obowiązujących w danej dyscyplinie w odniesieniu do nazw taksonomicznych, geoprzestrzennych i geologicznych oraz słów kluczowych. W miarę możliwości należy stosować terminy pochodzące ze standardowych taksonomii i słowników.
Zalecana zawartość plików README
-
Ogólne informacje
- Tytuł zbioru danych/pliku, do którego odnosi się plik README.
- Imię i nazwisko/nazwa instytucji/adres/adres e-mail (głównego badacza (lub osoby odpowiedzialnej za zebranie danych), współbadaczy, osoby do kontaktu w razie pytań).
- Data zebrania danych (może to być pojedyncza data lub przedział czasowy).
- Informacje o geolokalizacji zebrania danych.
- Słowa kluczowe użyte do opisania tematyki danych.
- Informacje o języku.
- Informacje o źródłach finansowania.
-
Informacje o plikach
- Krótki opis zawartości każdego pliku.
- Nazwa formatu pliku, jeśli nie wynika to jasno z jego nazwy.
- Jeśli zbiór danych obejmuje wiele powiązanych ze sobą plików, należy podać relacje między nimi lub opis struktury, w której się znajdują.
- Data utworzenia pliku.
- Data aktualizacji pliku (wersjonowania) oraz charakter aktualizacji.
- Informacje o powiązanych danych, które nie są częścią opisywanego zestawu danych.
-
Informacje dotyczące dostępu do danych
- Informacja o licencjach, na których są udostępnione dane, lub o ograniczeniu dostępu do danych.
- Linki do publikacji, które cytują lub wykorzystują dane.
- Linki do innych publicznie dostępnych lokalizacji danych.
- Zalecany sposób cytowania danych.
-
Informacje dotyczące metodologii badań
-
Opis metod gromadzenia lub generowania danych (w tym można podać odniesienia do publikacji lub innej dostępnej dokumentacji zawierającej opis badań).
-
Opis metod przetwarzania danych (należy opisać, w jaki sposób dane zostały wygenerowane).
-
Wszelkie informacje dotyczące oprogramowania lub sprzętu niezbędne do zrozumienia lub interpretacji danych, w tym numery wersji oprogramowania i sprzętu.
-
Informacja o procedurach zapewnienia jakości danych, np. kalibracja.
-
Definicje kodów lub symboli używanych do zaznaczania lub charakteryzowania danych o niskiej jakości/wątpliwych/wartości odstających, o których inni powinni wiedzieć.
-
Osoby zaangażowane w pobieranie, przetwarzanie, analizę i/lub przekazywanie próbek.
-
-
Informacje dotyczące danych
- W razie potrzeby należy powtórzyć tę sekcję dla każdego zbioru danych (lub pliku).
- Liczba zmiennych oraz rekordów.
- Lista zmiennych, zawierająca pełne nazwy i definicje (z rozpisaniem skrótów) nagłówków kolumn w przypadku danych tabelarycznych.
- Jednostki miary.
- Definicje kodów lub symboli używanych do rejestrowania brakujących danych.
- Specjalistyczne formaty lub inne używane skróty.