README na Githubie - robisz to źle!

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:

readme

Template

Przygotowałem dla Ciebie template, znajdziesz go tutaj.

readme template

Podsumowanie

Mam nadzieję, że dzisiejszy wpis był dla Ciebie pomocny w kwestii tworzenia lepszego README.

Do usłyszenia!

GitHubGitHubGitHub