Jak napisać readme projektu do portfolio?
W tym wpisie:
- poznasz przykładową strukturę readme,
- poznasz elementy, które powinien zawierać plik readme,
- dowiesz się czym jest plik readme?
Plik readme projektu to tekst, który wyświetla się na githubie pod plikami z repozytorium. W projektach komercyjnych zazwyczaj są tam wypisane kroki które pozwolą uruchomić nam projekt lokalnie. W projaktach open-source linki do dokumentacji, zasady kontrybucji i opis projektu. My skupimy się na strukturze pliku readme w projekcie do portfolio.
Pliki readme mają rozszerzenie .md, czyli markdown. Markdown to język znaczników, który został zaprojektowany do uproszczonego tworzenia i formatowania tekstu.
Ja też piszę moje wpisy za pomocą markdown, a później za pomocą bibliotek do konwertowania tekstu zamieniam go na plik html. Dzięki temu wpis szybciej ląduje na blogu.
Struktura readme projektu do portfolio.
1. Screen z aplikacji.
Na początek udostępniamy logo lub screen z aplikacji, który zachęci do wejścia dalej i sprawdzenia
aplikacji.
2. Opis projektu
Tutaj opisujemy co projekt robi. W jakim celu został stworzony i jakie problemy rozwiązuje.
Przykład:
FreightEx is platform that connects carriers, forwarding companies and clients that are looking for transport
services
lub
CRM it's a database fully integrated with google calendar, built for financial advisors to menage clients and team statistics - CRM, but it also includes some cool features. Enjoy!
3. Architektura.
Warto zobrazować jak aplikacja działa, z jakimi serwisami się komunikuje. Jeśli to prosta aplikacja,
która tylko komunikuje się z backendem wystarczy prosty schemat w postaci bloczków.
Przykład:
4. Tech stack.
W formie tabelki wypisujemy jakich frameworków, bibliotek i dlaczego takich
używamy w naszym projekcie.
Przykład:
5. Local development.
Wypisujemy kroki, które są potrzebne do uruchomienia aplikacji np. npm install, npm start
Przykład:
Prerequisite Node.js v20.*
git clone https://github.com/repo-link
npm install
cp .env.example .env
# set up environment variables
npm run dev
6. Skrypty w aplikacji.
W package.json na pewno posiadasz kilka skryptów, które są
odpowiedzialne za development i działanie aplikacji. Warto opisać, który skrypt za co odpowiada i po
co został zdefiniowany.
Przykład:
dev - running app locally
build - build app
lint - app linting using eslint
lint-fix - app linting and fixing auto fixable problems
preview - run built app
prettier - prettify code
prepare - script for husky
7. Link do live.
Rekruterzy niestety nie mają tyle czasu ile by chcieli, aby rozważyć kandydaturę osoby aplikującej, więc
nie pobierają i nie uruchamiają aplikacji lokalnie. Pozwól rekruterowi zapoznać się z aplikacją i umieść
w tej sekcji link do wersji live projektu. Teraz rekruter/ka może uruchomić aplikację jednym kliknięciem!
😎
8. Dostępy jeśli są potrzebne
Jeśli tworzysz aplikację, która wymaga logowania to w tej sekcji umieść login i hasło do konta testowego.
Alternatywą tego podejścia jest stworzenie w aplikacji przycisku do logowania kontem demo. Często zdarza
się, że rekruter/ka wchodzi na stronę kandydata aby zapoznać się z aplikacją, ale nie może się zalogować
i na tym jej/jego przygoda z Twoją aplikacją się kończy. 😔
Test User Login Data
Just click on Sign in with Google:
login: user@gmail.com
password: SomeStrongPassword123!@
9. Co zostało zrobione?
W formie listy wypisz najważniejsze funkcjonalności aplikacji.
Wypisz to czym chcesz się pochwalić.
10 .Plany na przyszłość.
Często w trakcie tworzenia aplikacji pojawiają się nowe pomysły, których jeszcze nie zdążyliśmy
zrealizować. W tej sekcji wypisz, co jeszcze można dodać do aplikacji.
11. Kontakt do autora.
Umieść tutaj swojego linkedina, maila itp.
Podsumowanie
Dzięki stworzeniu dobrego readme zwiększasz swoje szanse na pomyślną rekrutację. Dowiedziałeś/aś się czym jest plik readme. Poznałeś/aś jego przykładową strukturę i elementy które możesz w readme umieścić. Pamiętaj że to tylko przepis, który można modyfikować. Zaproponowana przeze mnie struktura to:
- Screen z aplikacji
- Opis projektu
- Architektura
- Tech stack
- Local development
- Skrypty w aplikacji
- Link do live
- Dostępy
- Co zostało zrobione?
- Plany na przyszłość
- Kontakt
Inny przykład: link do repozytorium