Zapisuj powody, nie tylko wynik#

Dokumentuj decyzję projektową, gdy wybór wpływa na architekturę, wymagania, bezpieczeństwo, koszty lub przyszłe zmiany. Diagram pokazuje wybrane rozwiązanie, ale zwykle nie wyjaśnia, dlaczego odrzucono alternatywy ani jakie kompromisy zaakceptowano. Utrwal kontekst, rozważane opcje, wybraną decyzję, uzasadnienie i konsekwencje.

Dokumentacja ma pozwolić przyszłemu zespołowi zrozumieć rozstrzygnięcie i ocenić, czy nadal obowiązuje. Nie opisuj każdej drobnej czynności; rejestr przeładowany nieistotnymi decyzjami trudno utrzymać.

Kiedy decyzja wymaga zapisu#

Zapis jest przydatny, gdy wybór nie jest oczywisty, ma istotny koszt zmiany, zależy od ograniczeń lub uzgodnień, wpływa na granice komponentów albo rozstrzyga sprzeczne wymagania. Warto też zachować kompromis, który później mógłby wyglądać jak przypadkowa wada.

Jeśli wybór jest lokalny, łatwo odwracalny i wynika bezpośrednio z konwencji, wystarczy kod, nazwa lub komentarz. Decyzje o znaczeniu dla kilku zespołów lub całego systemu powinny mieć stabilny identyfikator, status i właściciela.

Minimalny szablon#

Rekord może zawierać:

  • Identyfikator i tytuł: np. ADR-012: Płatności przez port dostawcy.
  • Status: proponowana, zaakceptowana, odrzucona, zastąpiona lub wycofana.
  • Data i właściciel: kto podjął decyzję i kto odpowiada za jej przegląd.
  • Kontekst: problem, wymagania, ograniczenia i założenia.
  • Opcje: realnie rozważane warianty wraz z zaletami i wadami.
  • Decyzja i uzasadnienie: co wybrano i dlaczego spełnia kryteria.
  • Konsekwencje: korzyści, koszty, ryzyka i działania do wykonania.
  • Powiązania: wymagania, diagramy, testy i inne decyzje.

Wypełnij tyle, ile potrzeba, by odtworzyć tok rozumowania. Odróżniaj potwierdzone fakty od założeń i zapisuj, kto ma potwierdzić niewiadome.

Łącz decyzje z modelem UML#

Odwołuj się do stabilnych identyfikatorów wymagań, diagramów i elementów modelu. Zapisz, który komponent, interfejs, relacja lub stan wynika z rozstrzygnięcia. Narzędzie modelujące może przechowywać takie relacje; w prostszym projekcie można użyć identyfikatorów w repozytorium dokumentacji.

Nie kopiuj do rekordu całego diagramu ani specyfikacji. Diagram opisuje strukturę lub zachowanie, a decyzja wyjaśnia powód i konsekwencje. Utrzymuj jedno miejsce jako źródło prawdy dla każdego szczegółu.

Przykład: zamówienia korzystają z interfejsu Płatności, a nie bezpośrednio z API konkretnego operatora. Diagram komponentów pokazuje zależność; zapis decyzji wyjaśnia, że granica ułatwia wymianę dostawcy. Konsekwencją są adapter, mapowanie błędów i dodatkowe testy kontraktowe.

Przykład krótkiego rekordu#

ADR-012 — Integracja płatności przez port

  • Status: zaakceptowana.
  • Kontekst: system może zmienić operatora płatności; logika zamówień nie powinna zależeć od protokołu dostawcy.
  • Opcje: bezpośrednie wywołanie operatora; wspólny interfejs z adapterem.
  • Decyzja: serwis zamówień korzysta z interfejsu Płatności realizowanego przez adapter.
  • Uzasadnienie: kontrakt izoluje domenę i ułatwia wymianę dostawcy.
  • Konsekwencje: potrzebne są adapter, mapowanie błędów, testy kontraktowe i monitoring.
  • Powiązania: diagram komponentów, scenariusz autoryzacji i wymagania dotyczące czasu odpowiedzi.

Rekord nie zastępuje specyfikacji interfejsu ani scenariusza. Tłumaczy, dlaczego granica komponentu istnieje i jaki kompromis za sobą pociąga.

Utrzymuj historię i aktualność#

Gdy decyzja przestaje obowiązywać, oznacz ją jako zastąpioną i wskaż nowy rekord. Zachowaj przyczynę zmiany, bo stare uzasadnienie może nadal wpływać na kod lub diagramy. Po zmianie przejrzyj powiązane wymagania, widoki i testy.

Wróć do rozstrzygnięcia, gdy zmieni się jego kontekst, np. koszty, obciążenie, wymogi prawne albo możliwości zespołu. Ponowna ocena nie oznacza automatycznego odrzucenia wcześniejszego wyboru; powinna prowadzić do jawnej decyzji.

Typowe błędy#

  • Zapis samego rozwiązania. Bez kontekstu nie wiadomo, jaki problem rozwiązano.
  • Brak alternatyw i kryteriów. Czytelnik nie może ocenić kompromisu.
  • Uzasadnienie bez dowodów. Zamiast „to najlepsza opcja” opisz wymaganie i konsekwencje.
  • Mieszanie faktu z założeniem. Oznacz niepewność oraz osobę odpowiedzialną za jej sprawdzenie.
  • Dokumentowanie wszystkiego. Skup się na rozstrzygnięciach o istotnych skutkach.
  • Duplikowanie specyfikacji. Odsyłaj identyfikatorem do źródła prawdy.
  • Brak konsekwencji i działań. Koszty wyboru pozostają niewidoczne.
  • Usunięcie nieaktualnego zapisu. Traci się historię i przyczyny wcześniejszego projektu.
  • Brak właściciela. Nikt nie wie, kto ma decyzję aktualizować.

Lista kontrolna#

  • Czy kontekst, ograniczenia i założenia są jawne?
  • Czy decyzja, status, data i właściciel są określone?
  • Czy rozważono realne opcje i kryteria wyboru?
  • Czy uzasadnienie i konsekwencje są zrozumiałe?
  • Czy są stabilne odwołania do wymagań, diagramów i testów?
  • Czy zapis zachowa historię, gdy zostanie zastąpiony?

Dobra dokumentacja pozwala zrozumieć, co zaprojektowano, dlaczego, przy jakich założeniach i za jaką cenę. Pisz zwięźle, wersjonuj decyzje i aktualizuj powiązane modele, gdy zmienia się kontekst.