Plik readme

Istnieje wiele różnych rodzajów dokumentacji, które można utworzyć w celu dołączenia do danych badawczych, a ich wybór zależy od kontekstu badań np. plik readme. 

Readme to plik dokumentacji, który pomaga innym użytkownikom interpretować i ponownie analizować zdeponowane dane. Powinien zawierać jasny i zwięzły opis wszystkich elementów zestawu danych. 

Plik readme ma za zadanie dostarczyć wszystkich niezbędnych informacji do właściwego zrozumienia, interpretacji i ponownego wykorzystania danych przez osoby, które chciałyby skorzystać z danych. Utworzenie pliku readme na początku procesu badawczego i konsekwentne jego aktualizowanie w trakcie badań pomoże w przygotowaniu ostatecznego pliku readme, gdy dane będą gotowe do zdeponowania. 

Dobrą praktyką jest tworzenie plików readme dla logicznych „klastrów” powiązanych plików/danych. W wielu przypadkach właściwe będzie utworzenie jednego dokumentu dla zbioru danych, który zawiera wiele powiązanych, podobnie sformatowanych plików, które są logicznie zgrupowane w celu ich późniejszego wykorzystania (np. zbiór skryptów Matlab). Czasami sensowne może być utworzenie pliku readme dla pojedynczego pliku danych. 

Napisz readme jako zwykły plik tekstowy  w języku angielskim, unikając w miarę możliwości zastrzeżonych formatów (np. MS Word). Sformatuj go tak, aby był łatwy do zrozumienia (np. oddzielaj ważne informacje pustymi liniami, zamiast umieszczać wszystkie informacje w jednym długim akapicie). O ile to możliwe, używaj terminów ze standardowych taksonomii i słowników.

Nazwij plik 00_readme, aby można go było łatwo znaleźć.  

Dlaczego warto taki plik przygotować i dołączyć do zbioru danych?

  • rzetelny opis projektu i danych pozwoli lepiej zrozumieć zawartość zbioru danych, 
  • informacja, z jakiego oprogramowania trzeba skorzystać przy formatach zamkniętych, jeśli w takich będą zdeponowane dane, przyspieszy wykorzystanie danych, 
  • opis, w jaki sposób są uporządkowane dane w zbiorze, pozwoli w pełni zweryfikować i wykorzystać dane, 
  • obszerny i pełny opis zwiększy zainteresowanie badaniami co może przełożyć się na nowe możliwości współpracy. 

Co powinien zawierać?

  • tytuł zbioru danych, opis i cel badania,
  • imię i nazwisko (ORCID)/instytucja/dane kontaktowe,
  • informację o metodzie i procedurach zbierania danych,
  • zakres czasowy badań,
  • narzędzia badawcze, 
  • strukturę uporządkowania danych:
    - strukturę folderów; 
    - system nazewnictwa plików (z przykładami);
    - relacje i zależności między plikami;
    - inne interesujące pliki dokumentacji w zbiorze danych (notatki, pliki towarzyszące);
    - przy każdym większym pliku krótki opis jego zawartości i data utworzenia;
    - opis systemu wersjowania plików, jeśli ma to zastosowanie. 
  • oprogramowanie wykorzystywane do gromadzenia i przetwarzania danych, w tym numery wersji; 
  • formaty plików używane w zbiorze danych i zalecane oprogramowanie; 
  • zastosowane procedury kontroli jakości; 
  • dziennik zmian zestawu danych; 
  • licencję, na jakiej dane są udostępniane. 

Przykładowy plik readme

Przewodniki jak przygotować dobry plik readme

Guide to writing “readme” style metadata

Good data practices

A Beginners Guide to writing a Kickass README

FAIR-Cheatsheets