Nie ma jednej poprawnej liczby#
Projekt potrzebuje tylu diagramów UML, ile jest konieczne, by odbiorcy podejmowali decyzje, rozumieli ważne zachowania i utrzymywali system. Nie istnieje obowiązkowe minimum ani uniwersalny zestaw typów. Mały projekt może skorzystać z kilku diagramów, a złożony system — z wielu widoków tworzonych dla różnych zespołów i celów.
Licz diagramy według pytań, na które odpowiadają, nie według typów dostępnych w UML. Jeden diagram może być nieczytelny, jeśli próbuje wyjaśnić wszystko. Z kolei pięć diagramów, które wszystkie pokazują te same zależności, tworzy koszt utrzymania bez dodatkowej wartości.
Zacznij od ryzyk i decyzji#
Zapytaj, jakie nieporozumienie lub ryzyko diagram ma usunąć. Czy zespół nie rozumie granicy systemu? Czy kilka usług musi współpracować w określonej kolejności? Czy cykl życia obiektu jest podatny na błędy? Czy rozmieszczenie artefaktów na węzłach wpływa na bezpieczeństwo lub dostępność?
Dobierz widok do odpowiedzi: diagram przypadków użycia dla celów i aktorów, klas dla pojęć i relacji, sekwencji dla komunikatów i chronologii, aktywności dla przepływu pracy, stanów dla cyklu życia, komponentów dla modułów i kontraktów, wdrożenia dla środowisk i artefaktów. Nie każdy projekt potrzebuje każdego rodzaju.
Praktyczny proces ustalania liczby#
- Zbierz pytania interesariuszy i decyzje, które wymagają wspólnego modelu.
- Określ odbiorców: analityków, programistów, testerów, architektów, operatorów lub użytkowników biznesowych.
- Zapisz, jaki zakres i poziom szczegółu jest potrzebny dla każdego pytania.
- Wybierz najmniejszy czytelny zestaw diagramów, który daje potrzebne odpowiedzi.
- Usuń widoki, które są duplikatem albo nie wpływają na decyzję, test lub utrzymanie.
- Sprawdź z odbiorcami, czy potrafią z diagramów odtworzyć wymagane reguły i przypadki.
- Ustal właściciela i zdarzenia, które uruchamiają aktualizację każdego widoku.
Liczba nie jest stała w czasie. Na etapie analizy może być potrzebny widok celów i pojęć, podczas projektowania — komponentów i interakcji, a w eksploatacji — wdrożenia oraz procedur zmian.
Diagramy w dokumentacji a szkice robocze#
W warsztacie zespół może tworzyć wiele krótkotrwałych szkiców. Nie każdy musi stać się trwałą dokumentacją. Zachowaj te, które wyjaśniają przyjętą decyzję, warunek akceptacji, istotną integrację, granicę lub ryzyko i których odbiorcy będą potrzebować później.
Szkic można usunąć po warsztacie, jeśli wynik i decyzja zostały zapisane gdzie indziej. Diagram utrzymywany jako część dokumentacji powinien mieć określony zakres, odbiorcę i właściciela. Liczba plików w repozytorium sama nie mierzy dojrzałości modelu.
Zestaw minimalny dla konkretnego celu#
Nie istnieje uniwersalny zestaw minimalny, ale można zdefiniować minimum dla pytania. Dla scenariusza integracji może wystarczyć jeden diagram sekwencji i kontrakt interfejsu. Dla architektury systemu mogą być potrzebne widoki komponentów i wdrożenia. Dla reguł zamówień przydadzą się model klas, aktywność procesu oraz maszyna stanów zamówienia, jeśli jego cykl życia jest istotny.
Zacznij od jednego widoku i dodaj następny tylko wtedy, gdy pierwszy nie odpowiada na inne ważne pytanie. To nie oznacza, że jeden diagram ma być przeciążony: rozdziel go, gdy czytelność wymaga osobnych perspektyw.
Koszt aktualizacji i źródło prawdy#
Każdy diagram wprowadza koszt: musi pozostać zgodny z wymaganiami, kodem i innymi widokami. Zmiany często pozostawiają nieaktualne obrazy, szczególnie gdy są kopiowane do wielu dokumentów. Określ, czy diagram jest źródłem prawdy, widokiem generowanym z modelu czy ilustracją, która wymaga ręcznej aktualizacji.
Automatyzacja może obniżyć koszt odświeżenia, ale nie gwarantuje merytorycznej poprawności. Wygenerowany diagram nadal powinien być sprawdzony pod kątem zakresu, czytelności, zgodności z intencją i pominiętych istotnych reguł.
Sygnały, że diagramów jest za dużo lub za mało#
Diagramów może być za dużo, gdy każdy rysunek powtarza ten sam model bez nowej perspektywy, nikt nie potrafi wskazać ich odbiorców lub żaden zespół nie utrzymuje ich po zmianach. Może być ich za mało, gdy ważne decyzje są interpretowane różnie, zachowanie graniczne nie jest testowalne albo krytyczne zależności istnieją tylko w wiedzy jednej osoby.
Równie ważna jest jakość i skala widoków. Jedna ściana elementów może funkcjonować jak wiele diagramów sklejonych w jeden, a krótkie, logicznie powiązane widoki bywają łatwiejsze do utrzymania.
Typowe błędy#
- Ustalony z góry obowiązkowy komplet. Potrzeby wynikają z projektu, a nie z listy typów UML.
- Więcej diagramów uznanych za lepszą dokumentację. Każdy widok musi dostarczać wartości.
- Jeden diagram dla całego systemu. Jeden rysunek może być zbyt duży i mieszać perspektywy.
- Tylko liczba diagramów jako miara kompletności. Istotne są pokrycie pytań, ryzyk i wymagań.
- Brak właściciela dokumentacji. Widoki bez odpowiedzialności szybko się dezaktualizują.
- Szkice robocze zachowane bez celu. Zachowuj wyniki, które będą używane lub uzasadniają decyzje.
- Generowanie bez przeglądu. Automatyczny obraz nie dowodzi zgodności z rzeczywistością.
Podsumowanie#
Projekt potrzebuje tylu diagramów, ile trzeba do wyjaśnienia ważnych decyzji, zachowań i ryzyk, przy akceptowalnym koszcie utrzymania. Wybieraj każdy widok według pytania i odbiorcy, usuwaj duplikaty, a odpowiedzialność za aktualizację ustalaj z góry.