README na GitHubie - robisz to źle!
- Czas potrzebny na przeczytanie:2 minuty
- Opublikowane:
README jest to plik z rozszerzeniem .md, czyli markdown. Markdown to, innymi słowy, język znaczników przeznaczony do formatowania tekstu.
Jeżeli jesteś nowy w środowisku githuba, czy też samego markdownu, możesz sprawdzić markdownową ściągawkę.
Po co to komu?
Bardzo często spotykam się ze źle zrobionym README w autorskich projekach na GitHubie. Wiele osób zaznacza tylko tytuł projektu i pozostawia plik pustym. Zdarzają się również przypadki, gdy README jest deafultowo wstawiane w przypadku różych technologii (Gatsby, CRA...), a autor projektu go nie tyka i zostawia tak, jak było przygotowane.
Dobre README pozwala innym zrozumieć co zawiera twój kod, w jakiej technologii jest napisany, o czym jest danych projekt i dlaczego jest godny uwagi!
Coraz częściej github jest wykorzystywany jako portfolio osoby starającej się o pracę. README warto przygotować tak, aby nawet osoba nietechniczna, na przykład HR, mogła z łatwością dowiedzieć się o wyżej wspomnianych rzeczach.
Co powinno zawierać dobre Readme?
- Overview czyli przegląd, krótki opis.
- Listę użytych technologii/bibliotek etc.
- Screenshoty.
- Informację o tym, jak zainstalować projekt.
- Informację o licencji, jeśli takową posiada.
- Odnośnik do wersji live projektu.
- Credits - zasługi dla innych, inspiracja.
- Przykładowy kod, szczególnie istotne w bibliotekach i narzędziach.
- Informacja o tym, gdzie użytkownik uzyska pomoc, gdy napotka jakieś problemy - mail, github issues itp.
Jeżeli twój plik README jest większych rozmiarów, możesz dodać Table of Contents.
Dodatkową opcją jest zamieszczenie informacji o tym, co sprawiło Ci problem i jak to rozwiązałeś, daje to obraz Twoich umiejętności w radzeniu sobie z napotkanymi problemami.
W projektach open source powinieneś zawrzeć zasady kontrybuowania i kodeks postępowania.
Plik Readme powinniśmy pisać zawsze w języku angielskim.
Inspiracja
Ucz się od najlepszych, poniżej znajdziesz kilka przykładów dobrze zrobionych README:
Template
Przygotowałem dla Ciebie template, znajdziesz go tutaj.
Podsumowanie
Mam nadzieję, że dzisiejszy wpis był dla Ciebie pomocny w kwestii tworzenia lepszego README.
Do usłyszenia!
