Uwaga! Trwają prace nad nową wersją serwisu. Mogą występować przejściowe problemy z jego funkcjonowaniem. Przepraszam za niedogodności!
⛔ Potrzebujesz wsparcia? Oceny CV? A może Code Review? ✅ Dołącz do Discorda!
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.
Chcesz być (lepszym) programistą i lepiej zarabiać? Umów się na rozmowę - powiem Ci jak to zrobić!
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?.
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.
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 😉
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.
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 🙂
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.
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).
Zamiast statycznego obrazu chcesz pokazać działanie projektu? Zobacz, jak uzyskać GIF i wstawić go do README!
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.
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.
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.
Jest to istotny element „oprowadzania” rekrutera po Twoim portfolio na GitHubie. Na tym etapie rekruter może zadawać sobie pytanie: co z innymi technologiami, które wypisałeś w CV lub które wymienione są w ogłoszeniu? Tę sekcję możesz więc umieścić właśnie w tym miejscu (do tej pory przekazałeś najważniejsze informacje) lub niżej – np. po sekcji z rozwiązaniami.
Najlepiej, jeśli podlinkowany projekt (lub projekty) będzie nawiązaniem do obecnego projektu, które może być odpowiedzią na pytania rekrutera. Jeśli więc masz projekt wykorzystujący komponenty klasowe Reacta, podlinkuj projekt z komponentami funkcyjnymi i hookami. Jeśli to prosta strona stworzona za pomocą HTML-a i CSS-a, linkuj do projektu ze stroną RWD czy metodologią BEM itd.
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 np. JSON Server czy przeprowadzić testy.
W tym punkcie wymień i opisz:
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.
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.
Zachęć odbiorcę do kontaktu z Tobą. Daj znać, że chętnie odpowiesz na pytania i podlinkuj np. swoje media społecznościowe.
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:
🔥 Podpowiedź: mały wycinek widoku z łatwością uzyskasz, stosując skrót klawiszowy narzędzia wycinania:
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ź 😉
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).
Gotowe! 🙂
Udostępnij ten artykuł:
Potrzebujesz cotygodniowej dawki motywacji?
Zapisz się i zgarnij za darmo e-book o wartości 39 zł!
PS. Zazwyczaj rozsyłam 1-2 wiadomości na tydzień. Nikomu nie będę udostępniał Twojego adresu email.
Chcesz zostać (lepszym) programistą i lepiej zarabiać?
🚀 Porozmawiajmy o nauce programowania, poszukiwaniu pracy, o rozwoju kariery lub przyszłości branży IT!
Umów się na ✅ bezpłatną i niezobowiązującą rozmowę ze mną.
Chętnie porozmawiam o Twojej przyszłości i pomogę Ci osiągnąć Twoje cele! 🎯