Zrób README
propozycje dobrego README
każdy projekt jest inny, więc zastanów się, która z tych sekcji Dotyczy twojego. Sekcje użyte w szablonie są sugestiami dla większości projektów open source. Należy również pamiętać, że podczas gdy README może być zbyt długi i szczegółowy, zbyt długi jest lepszy niż zbyt krótki. Jeśli uważasz, że README jest zbyt długi, rozważ użycie innej formy dokumentacji zamiast wycinania informacji.
Nazwa
Wybierz samodzielną nazwę dla swojego projektu.,
opis
daj znać, co konkretnie może zrobić twój projekt. Podaj kontekst i dodaj link do wszelkich referencji, których odwiedzający mogą być nieznani. Tutaj można również dodać listę funkcji lub podsekcję tła. Jeśli istnieją alternatywy dla Twojego projektu, jest to dobre miejsce na listę czynników różnicujących.
odznaki
na niektórych czytnikach można zobaczyć małe obrazy, które przekazują metadane, takie jak to, czy wszystkie testy przechodzą do projektu. Możesz użyć osłon, aby dodać trochę do README. Wiele usług posiada również instrukcje dodawania odznaki.,
wizualizacje
w zależności od tego, co robisz, dobrym pomysłem może być dołączenie zrzutów ekranu lub nawet filmu (często zobaczysz gify, a nie rzeczywiste filmy). Narzędzia takie jak ttygif mogą pomóc, ale sprawdź Asciinema dla bardziej wyrafinowanej metody.
instalacja
w obrębie określonego ekosystemu może istnieć wspólny sposób instalacji rzeczy, takich jak użycie Yarn, NuGet lub Homebrew. Rozważ jednak możliwość, że ktokolwiek czyta Twój README, jest nowicjuszem i chciałby uzyskać więcej wskazówek., Lista konkretnych kroków pomaga usunąć niejednoznaczność i umożliwia użytkownikom jak najszybsze korzystanie z projektu. Jeśli działa tylko w określonym kontekście, takim jak konkretna wersja języka programowania lub system operacyjny lub ma zależności, które muszą być zainstalowane ręcznie, należy również dodać podsekcję wymagania.
użycie
użyj przykładów i pokaż oczekiwany wynik, jeśli możesz. Warto mieć wbudowany najmniejszy przykład użycia, który można zademonstrować, zapewniając jednocześnie linki do bardziej wyrafinowanych przykładów, jeśli są zbyt długie, aby rozsądnie uwzględnić je w README.,
wsparcie
Powiedz ludziom, gdzie mogą udać się po pomoc. Może to być dowolna kombinacja śledzenia problemów, czatu, adresu e-mail itp.
Mapa Drogowa
Jeśli masz pomysły na Wydania w przyszłości, dobrze jest wymienić je w README.
wkład
Określ, czy jesteś otwarty na wkład i jakie są Twoje wymagania, aby je zaakceptować.
dla osób, które chcą wprowadzić zmiany w projekcie, pomocne jest posiadanie dokumentacji, jak zacząć., Być może istnieje skrypt, który powinni uruchomić lub niektóre zmienne środowiskowe, które muszą ustawić. Zrób te kroki wyraźnie. Te instrukcje mogą być również przydatne dla Twojego przyszłego ja.
Możesz również dokumentować polecenia do lint kodu lub uruchomić testy. Te kroki pomagają zapewnić wysoką jakość kodu i zmniejszyć prawdopodobieństwo, że zmiany nieumyślnie coś zepsują. Posiadanie instrukcji uruchamiania testów jest szczególnie przydatne, jeśli wymaga instalacji zewnętrznej, takiej jak uruchomienie serwera Selenium do testowania w przeglądarce.,
autorzy i podziękowania
okażcie uznanie tym, którzy przyczynili się do powstania projektu.
Licencja
dla projektów open source, powiedz jak jest licencjonowana.
status projektu
jeśli zabrakło Ci energii lub czasu na realizację projektu, umieść notatkę na górze README informującą, że rozwój spowolnił lub całkowicie się zatrzymał. Ktoś może zdecydować się na rozwidlenie twojego projektu lub zgłosić się jako opiekun lub właściciel, pozwalając Twojemu projektowi kontynuować. Możesz również złożyć wyraźne żądanie dla opiekunów.