Uwaga! Trwają prace nad nową wersją serwisu. Mogą występować przejściowe problemy z jego funkcjonowaniem. Przepraszam za niedogodności!

Jak napisać README do projektu na GitHubie

Dzięki niemu stworzysz świetne portfolio!

Odkładasz pisanie README „na kiedyś”? Zawróć z tej drogi póki możesz! Z tego artykułu dowiesz się, dlaczego powyższe podejście szkodzi, i otrzymasz masę wskazówek, jak napisać dobre README do projektu.

Spis treści

Chcesz dowiedzieć się więcej o GitHubie, README i Markdownie? Zapraszam do lektury artykułu Co to jest GitHub i do czego służy?.

Zadbaj o README zanim będzie Ci potrzebne

Dlaczego nie powinienem tworzyć README po zakończeniu projektu?

W maju zostawiłem w mieszkaniu kluczyki do samochodu. Zorientowałem się dopiero przed blokiem. Wróciłem więc na górę, wziąłem kluczyki, a w drodze na parking przywitałem się z sąsiadką.

Nic szczególnego. O czym tu pisać?

Przed takim pytaniem staniesz, gdy za README weźmiesz się już po zakończeniu projektu.

Gdybym prowadził dziennik, być może zapisałbym, że rosnący pod klatką bez już zakwitł, a moja córka właśnie skończyła 9 miesięcy. Szczegół warty odnotowania. Jak ten czas szybko leci!

Spotkana po drodze pani Hania prowadziła wesołego jamnika. Wyraźnie poprawiło mu się po operacji kręgosłupa. Kto by kiedyś uwierzył, że w ten sposób będziemy leczyć dyskopatię u psów? Ciekawostka warta odnotowania 😉

W ten sposób wygląda Twoja praca nad projektem. W jej trakcie często posiłkujesz się dokumentacją, tutorialami, artykułami; znajdujesz ciekawe pomysły, z których czerpiesz inspirację; dochodzisz do zaskakujących wniosków.

Jeśli nie odnotujesz tego od razu po „zarejestrowaniu”, to bardzo prawdopodobne, że Twoje README będzie wyglądać jak kilka pierwszych linijek tego fragmentu – dość biednie.

Mój projekt jest za prosty. Nie ma o czym pisać

Firma WebShine (nazwa zmieniona ;)) poszukiwała pracownika na stanowisko juniora. Szukali kandydata bez doświadczenia, który na początku swojej drogi zadowoli się przede wszystkim stylowaniem ich aplikacji.

Rekruter, wśród nadesłanych portfolio, znalazł sporo dobrze rozwiniętych projektów. Problem był tylko taki, że ich twórcy nie pokazali, czy potrafią ostylować elementy, ponieważ korzystali z gotowych bibliotek.

W końcu rekruter trafił na projekt landing page’a. Strona była zakodowana na podstawie darmowej templatki i ostylowana „ręcznie”. Dodatkowo prezentowała się dobrze w różnych rozdzielczościach.

Estetyczny opis projektu w README świadczył o tym, że kandydat świadomie tworzył kod i sięgał tylko po takie rozwiązania, których użycie potrafił uzasadnić. Nie zaśmiecał więc projektu niepotrzebnymi dodatkami.

Kandydat został zatrudniony.

Gdyby projekt nie posiadał opisu, rekruter nie poznałby wartości kandydata. Landing page zgubiłby się pośród wielu innych projektów.

Jak widzisz, nie chodzi o prezentację wyszukanych rozwiązań, ale o pokazanie, że świadomie korzystasz z tych „zwykłych”. Firmy poszukują pracowników, dla których projekt to w pierwszej kolejności plac budowy z określonymi zasadami, a nie piaskownica do eksperymentów 😉

Chcę mieć wystrzałowe README! Od czego zacząć?

Rób notatki. Wolisz kartkę i długopis? A może osobny plik na pulpicie? Bez względu na formę, zapisuj wszystko, co jest warte uwagi. Lepiej później wybierać spośród wielu informacji, niż próbować sobie przypomnieć choćby jedną.

Możesz też od razu utworzyć plik README.md w katalogu głównym swojego projektu i tam umieszczać notatki. Jeśli nie chcesz prowadzić historii zmian (commitów) dla README, to po prostu tymczasowo wrzuć README do pliku .gitignore.

Na początku podejmij 2 decyzje

README niczym dokumentacja?

Opisy projektów, na których uczysz się programowania, powinny trochę różnić się od opisów tworzonych np. do paczek npm.

Skup się na tym, aby zaprezentować rozwiązania problemów i sposób użycia konkretnych technologii. Pokaż, że Twoja praca jest przemyślana i że rozumiesz kolejne podejmowane kroki.

Niech Twoje README świadczy o tym, że masz świetne predyspozycje do rozwoju 🙂

Język angielski vs język polski

Dobrze jest pisać README po angielsku, lecz słaba znajomość tego języka nie powinna Cię powstrzymać przed posiadaniem opisu projektu.

Zawsze możesz stworzyć README po polsku, a potem przetłumaczyć je (czy samodzielnie, czy zlecając to komuś) na język angielski. Lepiej mieć jakieś README, niż nie mieć żadnego 🙂

Opis po polsku będzie plusem, jeśli np. chcesz pracować w małej lokalnej firmie. Wówczas obcojęzyczne README może nawet stanowić pewną barierę dla nietechnicznego rekrutera.

Jak zaplanować README – o czym pisać?

  • funkcjonalności programu – „co robi”, co można dzięki niemu osiągnąć. To pomoże Ci wprowadzić odbiorcę w tematykę projektu,
  • problemy, np. font skalujący się wraz ze zmianą rozmiarów kontenera, i ich rozwiązania. Tak przedstawisz kluczowe elementy projektu i pokażesz swój tok myślenia,
  • fragmenty kodu dla powyższych rozwiązań,
  • materiały, które pomogły Ci uzyskać dany efekt, np. clamp w CSS. Nawet jeśli później nie zamieścisz ich w README, to będziesz mógł z nich skorzystać, by wyjaśnić dane zagadnienie własnymi słowami,
  • reużywalne części projektu, np. helper ułatwiający pracę na elementach DOM czy walidację formularzy,
  • narzędzia – nie tylko te, z których korzystasz! 😉 Pamiętaj, że nawet narzędzia, z których zrezygnowałeś, mogą stać się interesującą częścią README. Posłużą do wyjaśnienia szczegółów projektu.
    Przykładowo: „W tej sytuacji można wykorzystać bibliotekę (…), lecz projekt został rozszerzony także o (…), co jest wystarczające do implementacji tej funkcjonalności”.
    Jest to świetny sposób na pokazanie, że nie mnożysz bezmyślnie bibliotek czy frameworków i świadomie planujesz swoje działania,
  • niezbędne paczki i komendy, które umożliwią pełne zapoznanie się z projektem, np. uruchomienie json-servera,
  • wtyczki – rozszerzenia do przeglądarki czy do IDE, które ułatwiły Ci pracę nad projektem. Będzie widać, że dbasz o rozwiązania usprawniające Twoją pracę,
  • inspiracje – czyli strony, aplikacje, grafiki, na których się wzorowałeś. Pokażesz w ten sposób, że potrafisz pracować z gotowymi materiałami. To również doskonała okazja, by napisać, co zrobiłeś inaczej (lepiej ;)),
  • pomysły na rozwój projektu. Zamieszczenie takiego pomysłu w README będzie miało sens, jeśli opiszesz, która część projektu jest np. na tyle uniwersalna, by przyjąć kolejne rozszerzenia. Postępując w ten sposób, pokażesz, że tworzysz rozwiązania otwarte na dalszy rozwój.

Jak uporządkować README + szablon

Screen

Jeśli Twój program ma warstwę wizualną, warto zaprezentować ją na screenie na górze README. Dzięki temu każdy, bez zagłębiania się w opis, będzie mógł wstępnie zapoznać się z projektem.

Pamiętaj, jeśli chcesz wykorzystać własny obraz, powinieneś dodać go do katalogu projektu i podać do niego ścieżkę, np. tak:
![a main page screenshot](./assets/screen.png).

Tytuł (nazwa)

Dobrze, by jednoznacznie wskazywał na przeznaczenie projektu (podobnie jak nazwa repozytorium). Niech osoby przeglądające Twojego GitHuba nie mają trudności ze zrozumieniem, z czym mają do czynienia.

Opis

Jest to dobre (bo widoczne) miejsce do podlinkowania podglądu na żywo. Nawet jeśli link do strony wyświetla się w pasku bocznym repozytorium (dzieje się tak, gdy umieścisz link w „About”), i tak warto jeszcze raz dodać przekierowanie. Nie wiesz, jak uzyskać link do podglądu? Sprawdź, jak podpiąć do projektu GitHub Pages.

Krótko przedstaw swój projekt: czym jest i do czego służy. Podstawowe funkcjonalności warto wymienić w punktach, dzięki czemu opis stanie się bardziej przejrzysty.

Użyte technologie

Jeśli chcesz skorzystać z ikon reprezentujących języki, biblioteki i frameworki, polecam źródło ikon na GitHubie. Wystarczy skopiować podany obok obrazu kod i umieścić go w swoim README.

Instalacja

Poinformuj, co potrzebne jest do uruchomienia projektu lokalnie. Być może ktoś zechce sprawdzić działanie Twojego kodu u siebie. Przyda mu się więc informacja o tym, jak np. zainstalować paczki, uruchomić lokalny serwer czy przeprowadzić testy.

Rozwiązania

W tym punkcie wymień i opisz:

  • problemy i ich rozwiązania poparte przykładami (screenami, fragmentami kodu),
  • narzędzia i wtyczki,
  • reużywalne części projektu (helpery, managery).

Jest to również dobre miejsce na zamieszczenie większej ilości screenów. Dla oszczędności miejsca możesz np. stworzyć jedną grafikę z kilku miniatur obrazów.

Wnioski na przyszłość / plany rozwoju projektu

W tym miejscu możesz opisać rozwiązania, które np. zamierzasz przetestować w kolejnym projekcie lub wdrożyć do obecnego.

Jeśli niektóre problemy programistyczne można było rozwiązać w inny sposób niż ten, na który się zdecydowałeś, również możesz o tym napisać, załączając krótkie uzasadnienie.

Kontakt do autora

Zachęć odbiorcę do kontaktu z Tobą. Daj znać, że chętnie odpowiesz na pytania i podlinkuj np. swoje media społecznościowe.

Inspiracje, podziękowania

Możesz tu krótko opisać, na czym się wzorowałeś (np. na darmowym szablonie), z jakich zadań/wyzwań korzystałeś (takich jak #JavaScript30) lub kto wspierał Cię w tworzeniu projektu.

Jeśli chcesz mieć podgląd tworzonych w Markdownie treści, możesz skorzystać z narzędzia StackEdit. Dzięki temu na bieżąco będziesz formatować nagłówki, elementy listy czy fragmenty kodu.

Przy pisaniu README możesz poszukać pomysłów na GitHubie lub skorzystać z szablonu.

👉 Przykładowe README:

🔥 Szablon README w Markdownie z instrukcją dla własnych notatek:

Szablon README

Ułatw odbiorcy odbiór – kilka tipów

  • Chcesz, by Twoje README przyjemnie się przeglądało?
    • Stosuj: nagłówki, listy, emotikony, wytłuszczenie słów kluczowych.
    • Dziel dłuższe treści na akapity. Nie twórz ścian tekstu! 🙂
    • Pozostaw przestrzeń między kolejnymi sekcjami (możesz to dego wykorzystać twardą spację:  ).
  • Unikaj rozbudowanych zdań.
  • Podawaj przykłady – są lepsze niż zawiłe tłumaczenia. Możesz coś pokazać przez fragment kodu lub screen? Wykorzystaj to!

🔥 Podpowiedź: mały wycinek widoku z łatwością uzyskasz, stosując skrót klawiszowy narzędzia wycinania:

  • Windows: klawisz Widnows + Shift + S (wycięty fragment pojawi się w schowku),
  • Mac: Command + Shift + 4 (wycięty fragment zostanie zapisany na Pulpicie).

 

RADME to coś więcej niż opis. Poprzez nie pokazujesz swoje mocne strony – swoją dokładność, sposób myślenia i podejście do rozwiązywania problemów. Tak zwieńczony projekt aż prosi się o to, by pochwalić się nim w mediach społecznościowych. Wykorzystaj to! Poniżej mała podpowiedź 😉

GRATIS – zaprezentuj projekt w social mediach jednym linkiem!

Gdy np. na Facebooku wklejamy jakiś link, często pojawia się grafika z linkowanej strony z krótkim opisem.

Taki sam efekt możemy uzyskać w przypadku repozytorium na GitHubie (zobacz przykład mojego posta na FB).

  1. Uzupełnij „About” w panelu bocznym repozytorium.
    Niech jest to kilka zdań o projekcie (treść możesz skopiować ze wstępu w README). Treść ta pojawi się pod grafiką wyświetloną w mediach społecznościowych.
  2. Dodaj obraz dla social mediów.
    W repozytorium projektu wejdź w zakładkę „Settings”. Znajdziesz tam sekcję „Social preview”. Dodaj do niej obraz, który ma reprezentować Twój projekt w mediach społecznościowych.

Gotowe! 🙂

Udostępnij ten artykuł:

Share on facebook
Share on linkedin
Share on twitter

Mentoring to efektywna nauka pod okiem doświadczonej osoby, która:

  • przekazuje Ci swoją wiedzę i nadzoruje Twoje postępy w zdobywaniu umiejętności,
  • uczy Cię dobrych praktyk i wyłapuje złe nawyki,
  • wspiera Twój rozwój i zwiększa zaangażowanie w naukę.