O co naprawdę chodzi w prawie aktualna dokumentacja" == bullshit?

Teza absolutna. I dlaczego jest uczciwa.

Dokumentacja albo jest, albo jej nie ma. Kropka.

Wiem, jak to brzmi. Za ostrze, za absolutnie, za mało niuansów. Zaraz ktoś napisze w komentarzu, że kontekst ma znaczenie, że to zależy od projektu, że przecież coś jest lepsze niż nic.

Nie jest.

Oto sedno problemu.

„80% aktualna” to nie dokumentacja. To pułapka. I to pułapka dużo bardziej niebezpieczna niż jej brak, bo działa cicho. Kiedy dokumentacja nie istnieje, zespół wie, że musi pytać, weryfikować, eksplorować. Kiedy dokumentacja prawie istnieje - zespół ufa. Czyta, zakłada, że to prawda, i działa na podstawie czegoś, co od sześciu miesięcy opisuje inny świat.

Pomyśl o mapie drogowej. Jeśli mapa jest pusta - wiesz, że musisz eksplorować. Jeśli mapa jest z 2019 roku i ktoś ją podpisał jako „80% aktualna” - jedziesz autostradą, której już nie ma. I nie wiesz, że jej nie ma, dopóki nie natkniesz się na roboty drogowe albo na drzewo w poprzek trasy.

Nieaktualna dokumentacja to nie zero. To minus. Marnuje czas każdego, kto w nią wejdzie. Wywołuje fałszywe poczucie bezpieczeństwa. I, co gorsza, buduje zaufanie do czegoś, co na to zaufanie nie zasługuje.

To nie puryzm. To pragmatyzm. Bo czas jest drogi, a zaufanie - jeszcze droższe.

Czym dokumentacja NIE jest. Trzy mity.

Mit 1: „Dokumentacja jest w kodzie.”

To jeden z ulubionych argumentów, który słyszę od dobrych inżynierów. I rozumiem skąd pochodzi - czytelny, dobrze napisany kod naprawdę może wiele powiedzieć. Ale kod opisuje jak. Dokumentacja opisuje dlaczego, dla kogo, i co się stanie, kiedy coś pójdzie nie tak.

Spotkałem kiedyś system, w którym „dokumentacją” był komentarz w kodzie: // TODO: opisać to kiedyś. Data komentarza: cztery lata wcześniej. Nikt nie wiedział, czy ktoś kiedyś opisał to gdzieś indziej, czy po prostu nigdy nie było na to czasu. Więc zespół pytał siebie nawzajem. Ustnie. Jak w kulturze przekazu plemiennego. Wiedza krążyła w głowach, a nie w dokumentach - co działało świetnie, dopóki połowa tych głów nie zmieniła pracy.

Kod jako jedyna dokumentacja to też zaproszenie dla konkretnej grupy odbiorców: programistów, którzy znają ten język, ten kontekst, ten system. Biznes nie wejdzie w repozytorium. Utrzymanie nie znajdzie w kodzie procedury na wypadek awarii o 3 w nocy. Użytkownik końcowy nie przeczyta klas i interfejsów, żeby dowiedzieć się, jak zresetować hasło.

Kiedy ostatnio widziałeś system, którego kod tłumaczy się sam - dla wszystkich odbiorców jednocześnie?

Mit 2: „Mamy dokumentację - jest projekt architektury z 2021.”

Projekt architektury to nie dokumentacja systemu. To wishful thinking zamrożony w PDF.

Dokumentacja opisuje istniejący, działający system - taki, jaki jest dziś, nie taki, jaki miał być trzy lata temu. W jednej firmie, gdzie przez kilka miesięcy robiłem przegląd, cała dokumentacja architektoniczna opisywała wersję „to-be”. System „as-is” nie istniał nigdzie poza głowami ludzi, którzy przy nim pracowali. A ci ludzie co chwilę odchodzili. Przy każdym odejściu firma traciła kawałek wiedzy o tym, jak naprawdę działa to, co zbudowali. Nikt tego nie liczył. Nikt nie łączył rotacji z rosnącym kosztem onboardingu i błędów produkcyjnych.

Projekt i dokumentacja to dwie zupełnie różne rzeczy. I mieszanie ich to przepis na chaos - o tym więcej za chwilę.

Mit 3: „Mamy dokumentację - jest na Confluence.”

Confluence to narzędzie. Nie gwarancja jakości, aktualności ani użyteczności tego, co w nim siedzi.

W jednej z firm znalazłem stronę z tytułem „Aktualna architektura systemu”. Data ostatniej edycji: trzy lata wcześniej. Pod spodem sześć komentarzy od programistów - jeden napisał, że ta funkcja już nie działa, drugi, że zmienili to w Q2, trzeci zapytał, czy to chodzi o poprzednią wersję. Nikt z nich nie zaktualizował strony. Każdy dodał komentarz i wrócił do pracy. I tak, przez trzy lata, dokument tytułowany „aktualny” opisywał system, który od dawna wyglądał inaczej.

Dokumentacja żywa. Bardzo żywa. Tylko że umarła dawno temu i nikt tego oficjalnie nie ogłosił.

Dokumentacja a projekt. To nie są synonimy.

Zanim przejdziemy do tego, jak tworzyć dokumentację, muszę zatrzymać się na jednym rozróżnieniu, które w praktyce miesza się nagminnie.

Dokumentacja to opis rzeczywistości. Opisuje system taki, jaki istnieje teraz - jego architekturę, zachowanie, integracje, ograniczenia, procedury. Kiedy ktoś czyta dokumentację, powinien być w stanie zrozumieć, jak system działa dziś, bez pytania kogokolwiek. Dokumentacja jest konsekwencją tego, co zostało zbudowane. Aktualizuje się razem z systemem. Jeśli system się zmienia, a dokumentacja nie - dokumentacja przestaje być dokumentacją i staje się historyczną ciekawostką.

Projekt (design doc, RFC, ADR) to opis oczekiwanego stanu docelowego. Opisuje to, co ma powstać lub dlaczego podjęto konkretną decyzję. To też wartościowy artefakt - szczególnie ADR-y, czyli Architecture Decision Records, które dokumentują dlaczego zdecydowano tak, a nie inaczej. Ale projekt to nie dokumentacja systemu. To dokument procesu myślowego i decyzyjnego. Projekt może być nieaktualny, może opisywać rzeczy, które ostatecznie nie powstały, może być wersją alfa czegoś, co w produkcji wygląda zupełnie inaczej.

Problem zaczyna się wtedy, kiedy projekt staje się jedyną „dokumentacją” - kiedy nikt nie opisuje tego, co naprawdę zostało zbudowane, bo przecież „mamy projekt architektury”. To tak, jakby oddać kupującemu plany budowlane zamiast kluczy do mieszkania i powiedzieć: „No przecież tu jest wszystko opisane.”

Distinkcja jest prosta:

• Projekt odpowiada na pytanie: „Co chcemy zbudować i dlaczego?“
• Dokumentacja odpowiada na pytanie: „Jak to, co zbudowaliśmy, działa naprawdę?“

Oba są potrzebne. Ale tylko jedno z nich mówi prawdę o tym, co dzieje się w produkcji o 3 w nocy.

Trzy proste kroki. Naprawdę proste.

Krok 1: Zacznij od ludzi, nie od treści

Zanim napiszesz cokolwiek - zapytaj, dla kogo to piszesz.

To nie jest filozofia ani zarządzanie przez cel. To lista ludzi, do których dzwonisz albo których zapraszasz na 30 minut. Programiści w zespole, programiści z innych zespołów, osoby z biznesu, utrzymanie, użytkownicy końcowi - każda z tych grup ma inną frustrację związaną z dokumentacją. Każda inna frustracja to wskazówka, co powinna zawierać dobra dokumentacja dla tej grupy.

Pytania, które warto zadać w każdej rozmowie: co musisz wiedzieć, żeby nie tracić czasu? Co się dzieje, kiedy czegoś nie wiesz? Gdzie szukasz odpowiedzi, kiedy dokumentacja nie pomaga?

Odpowiedzi zazwyczaj są inne dla każdej grupy. I to jest informacja sama w sobie.

Krok 2: Rozbij dokumentację na typy

Różne grupy, różne potrzeby. To oczywiste. A mimo to zdecydowana większość firm produkuje jedno monstrum - jeden wiki, jeden Confluence, jeden „central place for all documentation” - które nikomu nie pasuje, bo próbuje służyć wszystkim naraz.

Efektem dobrego kroku pierwszego jest lista kilku różnych dokumentów, a nie jeden dokument dla wszystkich. Programiści w tym samym systemie potrzebują architektury, ADR-ów i decyzji projektowych - najlepiej blisko kodu, w tym samym repozytorium, żeby zmiana w kodzie i zmiana w dokumentacji szły razem. Programiści z innych zespołów potrzebują kontraktów API, opisów eventów, schematów integracji - w formacie, który mogą konsumować automatycznie. Biznes potrzebuje opisu przypadków użycia, zachowania systemu i jego ograniczeń - w języku, który nie wymaga znajomości kodu. Utrzymanie potrzebuje runbooków i procedur incydentowych - prostych, jednoznacznych, napisanych na wypadek sytuacji, kiedy coś się wali o 3 w nocy i nie ma czasu na interpretację. Użytkownicy końcowi potrzebują instrukcji, FAQ, tutoriali - i to w miejscu, do którego sami dotrą bez pytania nikogo.

Każdy z tych dokumentów ma innego właściciela, inną częstotliwość aktualizacji i inny format. To nie jest jeden wiki. I to jest OK.

Krok 3: Zweryfikuj użyteczność - ten krok prawie nikt nie robi

To jest najważniejszy krok. I najczęściej pomijany - bo kiedy dokumentacja jest napisana, wszyscy są zmęczeni i chcą wrócić do prawdziwej pracy.

Ale napisanie dokumentacji to nie to samo co stworzenie użytecznej dokumentacji.

Kiedy masz gotowy dokument, idź do kogoś z grupy docelowej i powiedz: „Sprawdź, czy to jest dla ciebie użyteczne. Zrób z tym coś prawdziwego.” Usiądź obok. Obserwuj. Gdzie się zatrzymuje? Gdzie musi przewijać w kółko, bo nie może znaleźć odpowiedzi? Gdzie sięga po telefon, żeby zapytać kogoś zamiast korzystać z dokumentu?

To nie jest code review. To user testing dla dokumentacji. I działa dokładnie tak samo - bez niego nigdy nie wiesz, czy to co napisałeś jest zrozumiałe dla kogokolwiek poza tobą samym. Bo autor dokumentacji ma przekleństwo wiedzy - wie za dużo, żeby zobaczyć, czego w tekście brakuje.

Konkretne pytania, które warto zadać po sesji: czy po przeczytaniu tego wiesz, co zrobić? Czy jest tu coś, czego nie rozumiesz? Czy brakuje czegoś, czego szukałeś? I na koniec - powiedz mi własnymi słowami, co ten system robi.

Jeśli odpowiedź na ostatnie pytanie różni się od tego, co napisałeś - masz feedback. Użyteczny, darmowy i konkretny. I właśnie zaoszczędziłeś komuś dwie godziny szukania odpowiedzi w dokumencie, który kłamie.

Kto czego potrzebuje. Naprawdę.

Przykład jak wygląda u mnie strategia utrzymania dokumentacji:

Każdy wiersz to osobny właściciel. Osobny priorytet. Osobna odpowiedzialność za aktualność.

Jeśli przy każdej zmianie w systemie nie przeglądacie tej tabeli i nie pytacie „które dokumenty trzeba teraz zaktualizować?” - za kilka miesięcy macie dokumentację, której nie można zaufać. I zegar już chodzi.

A jeśli robicie w Agile lub Scrum - jest jeden konkretny ruch do wykonania teraz. Dopisz do swojego Definition of Done aktualizację każdego wymaganego dokumentu dla tej zmiany. Każdego. Przy każdym zakończonym przyroście. Bo jeśli nie aktualizujecie - lepiej usuńcie. Naprawdę. Pusta strona jest uczciwsza niż strona, która mówi nieprawdę.

…

Bo dokumentacja albo jest. Albo jej nie ma.

Nie ma czegoś takiego jak dokumentacja „prawie aktualna”. To jest jak „trochę w ciąży”. Albo jesteś, albo nie jesteś. I warto wiedzieć, po której stronie tej granicy stoisz - najlepiej zanim zapyta o to ktoś z zewnątrz.

Ile z Twojej dokumentacji możesz dziś zaufać bez sprawdzania?

I kiedy ostatnio zapytałeś kogoś spoza własnego zespołu, czy jest dla nich użyteczna?