Frontend Academy · Lekcja

Mentoring i dokumentacja techniczna

Mentoring i dokumentacja techniczna to bezpłatna lekcja Frontend Academy na CoddyKit. To lekcja 3 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Frontend Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Frontend Academy zawiera 4 lekcji w sumie.

Senior oznacza wzmacnianie innych

Na poziomie seniora zadaniem nie jest pisanie największej ilości kodu — chodzi o to, by rozwijać cały zespół. Należy mentorować osobom początkującym, pisać dokumentację, która skaluje Państwa wiedzę, prowadzić uczące przeglądy kodu i kształtować architekturę tak, aby inni mogli szybko i bezpiecznie pracować.

Mentoring przez programowanie w parach

Programowanie w parach to najszybszy sposób na rozwój osoby początkującej. Należy pracować razem (lub udostępnić ekran), pozwalając jej pisać kod, podczas gdy Państwo nawigują. Nie należy przejmować sterów — trzeba wyjaśniać tok rozumowania i zadawać pytania sokratejskie.

Wyzwania dopasowane do poziomu

Osobom początkującym należy dawać zadania nieco wykraczające poza ich obecne umiejętności. Zbyt łatwe zadania nie dają rozwoju. Zbyt trudne prowadzą do zagubienia i frustracji. Warto odpowiednio dobrać poziom: „Myślę, że poradzi sobie Pan/Pani z tym przy odrobinie pomocy — chętnie zaprogramuję to wspólnie, jeśli pojawią się trudności”.

Przegląd kodu jako nauczanie

W przypadku PR-ów osób początkujących należy wyjaśniać przyczynę każdej nietrywialnej uwagi. Warto dodawać odnośniki do odpowiedniej dokumentacji, wcześniejszych PR-ów lub artykułów. Zły przegląd: „użyj useCallback”. Dobry przegląd: „Ta funkcja jest tworzona na nowo przy każdym renderowaniu — przekazanie jej do komponentu potomnego opakowanego w memo powoduje niepotrzebne ponowne renderowanie. useCallback zapamiętuje funkcję. Oto przykładowy PR, w którym to zastosowaliśmy: #1234”.

Architectural Decision Records (ADR-y)

ADR dokumentuje istotną decyzję architektoniczną: co zdecydowaliśmy, dlaczego, jakie alternatywy rozważaliśmy i na jakie kompromisy się zgodziliśmy. Przyszłość podziękuje Państwu za to, co udokumentują Państwo dzisiaj.

# ADR-0007: Use TanStack Query for server state

Date: 2026-05-01
Status: Accepted

## Context
We currently scatter useEffect+fetch+useState patterns across the app.
Cache invalidation is inconsistent, race conditions cause stale data.

## Decision
Adopt TanStack Query (@tanstack/react-query v5) for all server state.

## Consequences
+ Built-in caching, deduplication, optimistic updates.
+ Standard pattern across team.
- Adds ~13KB gzipped.
- Team needs to learn query keys conventions.

## Alternatives Considered
- SWR: smaller, but fewer features (no mutations).
- Apollo Client: overkill (we don't use GraphQL).
- Custom hook: doesn't solve cache invalidation.

## References
- React Query docs: ...

Gdzie przechowywać ADR-y

ADR-y należy przechowywać w repozytorium, w katalogu docs/adr/, i numerować kolejno. Znajdują się obok kodu, którego dotyczą. Narzędzia: adr-tools i log4brains z przeglądarkowym interfejsem.

Jakość pliku README

Każdy pakiet, biblioteka i większa funkcja wymagają pliku README. Należy opisać: działanie, instalację, sposób użycia (z przykładami kodu), sposób wnoszenia zmian, uruchamianie testów i debugowanie. README-driven development polega na napisaniu najpierw pliku README, a następnie zbudowaniu rozwiązania zgodnie z tą specyfikacją.

Komentarze w kodzie — kiedy ich używać

Komentarze powinny wyjaśniać dlaczego, a nie co. Kod pokazuje, co się dzieje. Komentarze wyjaśniają: reguły biznesowe, nieoczywiste kompromisy, odnośniki do zadań i błędów oraz ostrzeżenia dotyczące pułapek.

// BAD: comment restates the code
// Increment counter by 1
counter++;

// GOOD: comment explains business context
// Stripe webhook can arrive twice — increment only if signature is fresh.
// See: https://stripe.com/docs/webhooks/best-practices#idempotency
if (!seen.has(event.id)) counter++;

Runbooki do zadań operacyjnych

Należy dokumentować powtarzalne lub ryzykowne zadania operacyjne: „Jak zmienić klucz API Stripe”, „Jak odzyskać sprawność po nieudanym wdrożeniu”, „Jak zdebugować wolną odpowiedź API”. Nowi członkowie zespołu będą mogli wykonać te czynności bez konieczności proszenia Państwa o pomoc.

Żywa dokumentacja

Nieaktualna dokumentacja jest gorsza niż jej brak. Należy ją datować. Warto przeglądać ją co kwartał. Dokumentację, której nikt nie aktualizuje, należy usuwać. Jeszcze lepiej: generować dokumentację z kodu (Storybook dla komponentów, TypeDoc dla API, OpenAPI dla endpointów).

Prezentacje techniczne i brown-bagi

Warto prowadzić dla zespołu 20–30-minutowe prezentacje o tym, czego się Państwo nauczyli: nowej bibliotece, historii debugowania lub przydatnym wzorcu. Zmusza to do uporządkowania własnego sposobu myślenia i uczy innych.

Budowanie bezpieczeństwa psychologicznego

Osoby początkujące, które boją się zadawać pytania, nie rozwijają się. Należy normalizować stwierdzenie „Nie wiem”. Trzeba stworzyć bezpieczne warunki do popełniania błędów — doceniać analizę po incydencie, a nie szukać winnych. Jako senior nadają Państwo ton całemu zespołowi swoimi reakcjami.

Pułapka bohaterskiego kodowania

Nie należy być osobą, która samodzielnie naprawia każdy incydent na produkcji. Trzeba udokumentować rozwiązanie, następnym razem pracować w parze z członkiem zespołu i zautomatyzować diagnozowanie. Zespół, który potrzebuje Państwa bohaterskich działań, jest kruchy.

Szybkie sprawdzenie

Jaki jest główny cel Architectural Decision Record (ADR)?

Podsumowanie: mentoring i dokumentacja

Senior oznacza wzmacnianie innych, a nie pisanie największej ilości kodu. Należy programować w parach i uczyć przez przeglądy kodu, a także dawać wyzwania dopasowane do poziomu. ADR-y w docs/adr/ rejestrują przyczyny podjęcia decyzji. Każdy pakiet powinien mieć plik README. Komentarze wyjaśniają dlaczego, a nie co. Runbooki służą do zadań operacyjnych. Żywa dokumentacja (Storybook, TypeDoc, OpenAPI) jest lepsza od statycznych plików Markdown. Należy budować bezpieczeństwo psychologiczne i unikać bohaterskiego kodowania.

Często zadawane pytania

Czy lekcja „Mentoring i dokumentacja techniczna” jest bezpłatna?

Tak — pełny tekst „Mentoring i dokumentacja techniczna” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Frontend Academy, przejdź na CoddyKit PRO. Kurs Frontend Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Mentoring i dokumentacja techniczna”?

Rozwinie Pan/Pani umiejętności młodszych członków zespołu dzięki programowaniu w parach i odpowiednio przekazywanym informacjom zwrotnym, napisze ADR-y dotyczące decyzji architektonicznych oraz będzi… Ćwiczysz Frontend Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Frontend Academy?

Nie wymagamy żadnego doświadczenia. Frontend Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 3 z 4.

Ile czasu zajmuje lekcja „Mentoring i dokumentacja techniczna”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Frontend Academy?

Tak. Każda lekcja Frontend Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

Rozmowy rekrutacyjne z projektowania systemów frontendowych
Kultura code review i dobre praktyki PR
Mentoring i dokumentacja techniczna
Bycie na bieżąco: specyfikacje i propozycje

← Powrót do Frontend Academy