Dokumentacja projektu - co, gdzie i jak zapisywać

Dlaczego dokumentacja ma znaczenie

Każdy zespół ma osobę, która "wie wszystko" - jak działa ten moduł, dlaczego wybraliśmy tę bazę danych, gdzie leży konfiguracja produkcyjna. Problem pojawia się gdy ta osoba idzie na urlop, zmienia pracę albo po prostu zapomina.

Dokumentacja to nie biurokracja. To pamięć zespołu. Bez niej każde pytanie wymaga rozmowy, każdy nowy członek zespołu zaczyna od zera, a decyzje podejmowane pół roku temu trzeba podejmować ponownie bo nikt nie pamięta kontekstu.

Dobra dokumentacja oszczędza godziny pracy tygodniowo. Zła dokumentacja (nieaktualna, niekompletna, nieznajdowalna) jest gorsza niż jej brak - bo ludzie jej ufają i podejmują błędne decyzje.

Co dokumentować - zasada 80/20

Nie musisz dokumentować wszystkiego. Dokumentuj to co kosztuje czas gdy jest niejasne:

• Decyzje architektoniczne - dlaczego wybraliśmy PostgreSQL a nie MongoDB, dlaczego mikrousługi a nie monolit. Kontekst decyzji jest ważniejszy niż sama decyzja.
• Jak uruchomić projekt - od zera do działającej aplikacji lokalnie. README powinno wystarczyć nowemu deweloperowi na pierwszy dzień.
• Procesy zespołowe - jak robimy code review, jak wdrażamy na produkcję, jak zgłaszamy bugi. Rzeczy które powtarzają się i powinny być spójne.
• API i integracje - jak komunikują się nasze serwisy, jakie są endpointy, jakie formaty danych.
• Nietypowe rozwiązania - jeśli coś działa nieintuicyjnie, napisz dlaczego. "Ten timeout jest ustawiony na 30 sekund bo zewnętrzny serwis X odpowiada wolno w godzinach szczytu" - oszczędzi komuś godziny debugowania.

Czego nie dokumentować:

• Rzeczy które wynikają wprost z kodu (jeśli kod jest czytelny, nie pisz komentarza "ta funkcja dodaje dwa liczby")
• Tymczasowe ustalenia które zmienią się za tydzień
• Szczegóły implementacyjne które można odczytać z kodu

README - wizytówka projektu

README to pierwszy plik który czyta każdy nowy w projekcie. Powinno zawierać:

• Co to jest - jedno zdanie opisujące projekt. Nie misja firmy, nie historia - po prostu co robi ta aplikacja.
• Jak uruchomić - krok po kroku, od sklonowania repo do działającej aplikacji. Testuj to regularnie - nic nie jest bardziej frustrujące niż README które nie działa.
• Wymagania - wersje języka, bazy danych, narzędzia. Najlepiej z dokładnymi wersjami.
• Struktura projektu - krótki opis katalogów i gdzie szukać czego. Szczególnie ważne w większych projektach.
• Jak wdrożyć - lub link do dokumentu o wdrożeniu.

Dobry test README: daj je komuś kto nie zna projektu i obserwuj. Jeśli musi pytać - README wymaga poprawy.

ADR - Architecture Decision Records

ADR to prosty format dokumentowania decyzji architektonicznych. Każdy ADR to krótki dokument z czterema sekcjami:

• Kontekst - jaki problem rozwiązujemy, jakie mamy ograniczenia
• Decyzja - co postanowiliśmy zrobić
• Konsekwencje - co z tego wynika, jakie są tradeoffs
• Status - zaakceptowany, odrzucony, zastąpiony przez inny ADR

Przykład: "ADR-003: Używamy Redis do cache zamiast Memcached. Kontekst: potrzebujemy cache z obsługą struktur danych (sorted sets). Decyzja: Redis. Konsekwencje: dodatkowa zależność, ale mamy sorted sets i pub/sub."

ADR-y trzymaj w repozytorium obok kodu. To żywa historia projektu - za rok nikt nie będzie pamiętał dlaczego wybraliśmy Redis, ale ADR będzie.

Wiki vs dokumenty vs kod

Gdzie trzymać dokumentację? Zależy od typu:

• W repozytorium (Markdown) - README, ADR-y, dokumentacja API, instrukcje deweloperskie. Blisko kodu, wersjonowane razem z nim, łatwe do aktualizacji w ramach PR.
• Wiki - procesy zespołowe, onboarding, instrukcje nietechniczne, informacje o infrastrukturze. Łatwiejsze do edycji dla osób nietechnicznych.
• Komentarze w zadaniach - decyzje dotyczące konkretnych funkcjonalności, kontekst dlaczego coś zrobiliśmy tak a nie inaczej. Powiązane z konkretną pracą.

Zasada: dokumentacja która zmienia się razem z kodem powinna być w repo. Dokumentacja procesowa i organizacyjna w wiki. Kontekst decyzji przy zadaniach.

Jak pisać dobrą dokumentację

Dokumentacja to nie praca dyplomowa. Kilka zasad dobrego pisania:

• Pisz dla konkretnego czytelnika - nowy deweloper? Product owner? Klient? Każdy potrzebuje innego poziomu szczegółowości.
• Zacznij od "dlaczego" - nie "ten moduł eksportuje dane do CSV". Raczej "klienci potrzebują eksportu danych do swoich systemów BI, więc ten moduł generuje raporty CSV".
• Używaj przykładów - jeden dobry przykład jest wart akapitu opisu. Pokaż request i response, pokaż komendę i wynik.
• Krótkie akapity - ściana tekstu odstrasza. Listy punktowane, nagłówki, krótkie zdania.
• Nie pisz "oczywistych" rzeczy - to co jest oczywiste dla Ciebie dziś, może nie być oczywiste dla kogoś za pół roku. Ale nie opisuj każdego kroku jak dla dziecka.

Utrzymywanie dokumentacji aktualnej

Największy problem z dokumentacją: starzeje się. Kod ewoluuje, dokumentacja zostaje. Po kilku miesiącach opisuje rzeczywistość, która już nie istnieje.

Jak temu zapobiec:

• Dokumentacja jako część PR - zmienił się API? Zaktualizuj docs w tym samym PR. Nie "zrobię to później" - później nigdy nie nadchodzi.
• Regularne przeglądy - raz na kwartał przejrzyj dokumentację i usuń lub zaktualizuj nieaktualne fragmenty. Zaplanuj to jak każde inne zadanie.
• Właściciele dokumentów - każdy ważny dokument ma właściciela. Nie oznacza to że tylko on może edytować - ale odpowiada za aktualność.
• Data ostatniej aktualizacji - widoczna na każdym dokumencie. Jeśli dokument nie był aktualizowany od roku, czytelnik wie że trzeba zweryfikować informacje.
• Mniej znaczy więcej - lepsza krótka aktualna dokumentacja niż rozbudowana nieaktualna. Usuń to czego nikt nie czyta.

Dokumentacja dla nowych osób

Onboarding to najlepszy test jakości dokumentacji. Jeśli nowa osoba musi ciągle pytać o rzeczy, które powinny być opisane - dokumentacja wymaga pracy.

Minimum dla onboardingu:

• Lista narzędzi i dostępów do uzyskania (z linkami i kontaktami)
• Jak postawić środowisko deweloperskie krok po kroku
• Architektura systemu - diagram i opis w jednym zdaniu na komponent
• Kto jest kim - role w zespole i do kogo z jakimi pytaniami
• Pierwsze zadanie - proste zadanie do wykonania pierwszego dnia, żeby nowa osoba przeszła cały cykl od brancha do wdrożenia

Narzędzia do dokumentacji

Nie szukaj idealnego narzędzia - szukaj takiego, którego zespół będzie używał:

• Markdown w repo - bezkosztowe, wersjonowane, blisko kodu. Idealny dla dokumentacji technicznej.
• Notion / Confluence - rich text, szablony, łatwa nawigacja. Dobre dla dokumentacji procesowej i wiki zespołu.
• Komentarze w narzędziu projektowym - kontekst przy zadaniach, decyzje powiązane z konkretnymi zmianami.

Podsumowanie

Dokumentuj decyzje, nie oczywistości. Trzymaj dokumentację blisko kodu. Aktualizuj ją razem ze zmianami w projekcie. I pamiętaj: najlepsza dokumentacja to taka, której nie musisz szukać - bo jest tam gdzie jej szukasz.