Kategoria:Inne

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!

O autorze

Olaf Sulich

Olaf jest Frontend Developerem, blogerem i nosi rybacki kapelusz 🎩 Pisze o wszystkim co związane z frontendem, ale nie boi się backendu i designów 🦾 Ma głowę pełną pomysłów i nadzieję, że znajdziesz tutaj coś dla siebie!

Dołącz do społeczności!

Bo w programowaniu liczą się ludzie

Wchodzę