Jak napisać plik README TXT: Poradnik od kogoś, kto sam to przeszedł

Szczerze mówiąc, stworzenie ładnie ustrukturyzowanego pliku README TXT może wydawać się nudne i monotonne, ale uwierz mi, to niezwykle ważne, jeśli planujesz udostępnić swój zbiór danych lub projekt innym. Zdecydowanie byłem w takiej sytuacji, gdy miałem surowe dane, żadnego wyjaśnienia i nie miałem pojęcia, o co chodzi, a to tylko wprowadzało chaos. Oto więc prosty sposób na stworzenie porządnego pliku README — nic wyszukanego, tylko tyle informacji, żeby ktoś inny (lub Ty w przyszłości) mógł zrozumieć, o co w tym wszystkim chodzi.

Otwieranie edytora tekstu: rozpoczęcie całej operacji

Po pierwsze, chwyć dowolny edytor tekstu, z którym czujesz się komfortowo. W systemie Windows działa Notatnik, ale jeśli jesteś bardziej zaawansowany, może Notepad++, lub po prostu zachowaj prostotę — TextEdit na Macu w trybie tekstu zwykłego. Linux? Prawdopodobnie gedit, nano lub cokolwiek jest w Twojej dystrybucji. Szczerze mówiąc, używałem też vima, co jest trochę przesadą, jeśli dopiero zaczynasz. W każdym razie, otwórz go; wszystko, co tutaj robisz, to wpisywanie podstawowych informacji — nie jest potrzebne formatowanie ani tekst sformatowany. Po prostu zwykły tekst. Zapisz go jako README.txt— niech będzie oczywiste, gdzie należy. Jeśli masz dedykowany folder dla swojego projektu, zapisz tam plik README wraz z plikami danych. Użyj Plik > Zapisz jako, wybierz Zwykły tekst (*.txt). Proste.

Nazwa pliku README: Jak go nazwać?

Na samej górze wpisz nazwę swojego zbioru danych lub projektu – to nie tylko symbol zastępczy, ale kotwica, która wszystko wyjaśnia. Zamiast po prostu nazwać go „CZYTAJ MNIE”, napisz bardziej szczegółowo: Climate_Data_2024.txt. W ten sposób, przewijając później folder, nie pomylisz się, co jest czym. Może się to wydawać trywialne, ale oszczędza mnóstwo czasu. Pomyśl o tym jak o etykietowaniu skrzynki z narzędziami, aby nie wyciągać przypadkowych rzeczy, gdy faktycznie potrzebujesz danych pogodowych.

Lista osób, które to stworzyły i wszelkie linki DOI

Teraz uwzględnij listę autorów lub swojego zespołu. Może po prostu swoje imię i nazwisko, jeśli to solowy projekt. Jeśli istnieje DOI — to cyfrowy identyfikator obiektu, coś w rodzaju stałego łącza do danych lub publikacji — dodaj go. Zazwyczaj można go uzyskać z repozytoriów takich jak Zenodo, DataCite, a nawet GitHub. Na przykład: https://doi.org/xx/xxxxx. Dołączenie DOI ułatwia cytowanie zestawu danych i dodaje wiarygodności, zwłaszcza jeśli inni będą go ponownie wykorzystywać. Jeśli nie jesteś pewien, czy powinieneś, pomyśl: „Czy ktoś będzie chciał to później zweryfikować lub zacytować?”.Jeśli tak, dodaj ten DOI. I zgodnie z najlepszymi praktykami, niech będzie prosty, ale kompletny — nikt nie chce zgadywać, kto to stworzył ani skąd to pochodzi.

Dodawanie dat utworzenia i ostatniej aktualizacji

Następnie zanotuj, kiedy utworzyłeś plik README i kiedy ostatnio go aktualizowałeś. Możesz wpisać datę ręcznie — np.2024-04-25 — lub, jeśli chcesz się popisać, użyć narzędzi wiersza poleceń, aby ją wygenerować. Na przykład na komputerach Mac/Linux polecenie date, a w systemie Windows PowerShell.Get-DateAle szczerze mówiąc, samo wpisanie działa dobrze. Ta informacja jest naprawdę przydatna, zwłaszcza jeśli z czasem aktualizujesz zestawy danych lub dokumentację. Dobrze jest również wspomnieć, czy istnieje nowsza wersja jakichkolwiek powiązanych plików, aby ludzie wiedzieli, że przeglądają najnowsze informacje. Jeśli Twój zestaw danych będzie regularnie aktualizowany, rozważ dodanie numeru wersji, np.v1.0 lub jakiejś notatki „ostatnia aktualizacja”, aby zachować przejrzystość. To nie jest wyszukane, ale pomaga uniknąć nieporozumień w przyszłości.

Dokumentowanie zmiennych, terminów lub kolumn danych

Tutaj w końcu przeszedłem do szczegółów — wypisz wszystkie zmienne, cechy lub kluczowe terminy w danych. Bądź super opisowy. Na przykład, jeśli twój zestaw danych rejestruje temperatury, określ, czy są to stopnie Celsjusza czy Fahrenheita — jak Temperatura (°C). To samo dotyczy innych pomiarów: ciśnienia, wilgotności, poziomów pH, czegokolwiek. Jeśli nie jesteś pewien, co oznacza dany termin lub jakie jednostki są używane, zaznacz go znakiem zapytania, jak Poziom pH [?]. W ten sposób przyszli użytkownicy, a nawet ty sam później, będą wiedzieć, że musisz to sprawdzić. Ponadto, jeśli twoje dane używają określonych układów współrzędnych lub ram odniesienia — jak WGS84 dla danych geograficznych — dodaj te informacje. Dodatkowe punkty, jeśli dołączysz szybki przykład dla każdej zmiennej, więc będzie jasne, jakich wartości się spodziewać.

---

Podsumowując, trzymanie się tego luźnego szablonu sprawia, że ​​plik README jest czymś więcej niż tylko pustą stroną. To szybka mapa drogowa dla każdego (w tym, szczerze mówiąc, dla Ciebie w przyszłości), która pomoże Ci zrozumieć, co jest w środku i jak to wszystko zostało skonstruowane. Przyznam, że zajęło mi kilka prób, zanim zorientowałem się, ile szczegółów dodać i gdzie umieścić datę ostatniej aktualizacji, aby nie przeciążyć pliku. Ale majstrowanie nawet przy prostym pliku tekstowym jest lepsze niż po prostu pozostawienie wszystkiego bez dokumentacji — uwierz mi.

Mam nadzieję, że to pomogło — zajęło mi zdecydowanie za dużo czasu, żeby to wszystko ogarnąć. Powodzenia i udanego dokumentowania! Przynajmniej to lepsze niż to niejasne „README”, które ignorowałem tygodniami.

---

---