Aktualizuj, gdy zmienia się znaczenie, które diagram ma przekazywać#
Dokumentację UML aktualizuj wtedy, gdy zmienia się modelowany kontrakt, odpowiedzialność, zachowanie, architektura, wdrożenie lub decyzja, a diagram nadal jest używany do ich wyjaśniania. Nie każda zmiana kodu wymaga edycji diagramu: jeśli szczegół leży poza jego zakresem, aktualizacja może nie być potrzebna. Liczy się zgodność z deklarowanym celem i źródłem prawdy.
Diagram, który regularnie wprowadza odbiorców w błąd, należy poprawić, oznaczyć jako nieaktualny albo usunąć. Cicha rozbieżność jest groźniejsza niż jawny brak dokumentacji, bo odbiorca może zaufać nieprawdziwej informacji.
Zmiany, które zwykle wymagają przeglądu#
Sprawdź odpowiednie widoki UML, gdy zmieniają się:
- publiczne interfejsy, granice komponentów, integracje lub ich właściciele;
- krytyczne scenariusze, reguły biznesowe, warunki i wyniki;
- stany obiektów, przejścia, wyjątki albo odpowiedzialność za cykl życia;
- struktura danych i powiązania, które diagram ma dokumentować;
- topologia, środowiska, lokalizacja artefaktów lub wymagania wdrożeniowe;
- wymagania bezpieczeństwa, dostępności, wydajności lub zgodności;
- decyzje architektoniczne, które uzasadniają model.
Zmiana nazwy prywatnej funkcji pomocniczej nie musi wymagać modyfikacji przeglądowego diagramu architektury. Zmiana publicznego kontraktu lub odpowiedzialności może wymagać aktualizacji diagramu interfejsów, scenariuszy i dokumentacji integracji.
Włącz aktualizację do procesu zmian#
Najłatwiej utrzymać dokumentację, gdy jej przegląd jest częścią pracy nad zmianą. W opisie zadania lub pull requestu zapytaj, które diagramy ulegają zmianie; podczas przeglądu porównaj model ze zmianą; po akceptacji wygeneruj grafiki ponownie, jeśli pochodzą ze źródeł tekstowych.
Dla modeli w narzędziach wizualnych aktualizuj źródłowy model, nie tylko zrzut ekranu. Dla diagramów tekstowych przechowuj kod źródłowy obok dokumentacji i generuj wynik z tego kodu. Plik PNG bez edytowalnego modelu staje się trudny do modyfikowania i sprawdzania.
Właściciel, zakres i źródło prawdy#
Każdy trwały diagram powinien mieć właściciela odpowiedzialnego za zakres, nomenklaturę i przegląd zmian. Właścicielem może być zespół, nie jedna osoba. Zapisz, czy diagram jest aktualnym źródłem modelu, automatycznie generowanym widokiem, szkicem czy ilustracją do artykułu.
Jeśli kod jest źródłem prawdy dla API, diagram nie powinien być utrzymywany jako niezależna ręczna kopia wszystkich sygnatur. Jeśli diagram jest modelem architektury, jego intencja może wykraczać poza kod i musi być recenzowana jako osobny artefakt. Uzgodnij, jak rozwiązywać rozbieżności.
Częstotliwość i zdarzenia aktualizujące#
Nie ma jednego kalendarzowego interwału odpowiedniego dla wszystkich diagramów. Widoki wysokiego ryzyka — integracje, bezpieczeństwo i wdrożenie — sprawdzaj przy zmianach, które ich dotyczą. Diagram przeglądowy można kontrolować podczas planowanych przeglądów architektury, o ile nie zastępuje to aktualizacji po istotnym zdarzeniu.
Ustal wyzwalacze: zmiana interfejsu, nowa usługa, migracja danych, istotny incydent, zmiana zakresu systemu, zakończenie etapu projektu lub przeniesienie odpowiedzialności. Warto dodać automatyczną walidację źródeł tekstowych, linków i renderowania, ale test składni nie potwierdza, że semantyka jest aktualna.
Jak postąpić z nieaktualnym diagramem#
Najpierw ustal, czy diagram nadal jest potrzebny. Jeśli tak, popraw go i wskaż aktualną wersję. Jeśli już nie jest używany, przenieś go do archiwum albo usuń z aktywnej dokumentacji; zachowaj historię zgodnie z praktyką projektu. Jeśli aktualizacja nie jest możliwa, oznacz diagram jako nieaktualny, podaj datę stanu i wskaż, czego nie należy z niego wywnioskować.
Nie poprawiaj wyłącznie obrazu, jeśli model źródłowy jest rozbieżny. Zaktualizuj źródło, zweryfikuj diagram, a następnie wygeneruj obraz. Dzięki temu kolejna zmiana nie odtworzy starej wersji.
Przegląd jakości po aktualizacji#
Po zmianie sprawdź, czy diagram nadal odpowiada na swoje pytanie, ma spójne nazwy i poprawne strzałki, liczności, warunki oraz relacje. Zweryfikuj go z innymi diagramami i tekstem, które opisują tę samą granicę. Upewnij się, że wygenerowany obraz jest czytelny, a linki i odwołania prowadzą do właściwych materiałów.
Typowe błędy#
- Aktualizacja dopiero po incydencie. Włącz przegląd modelu do zmian kontraktów i architektury.
- Każdy commit uznany za powód edycji. Aktualizuj widoki, których znaczenie lub dane rzeczywiście się zmieniają.
- Brak właściciela. Zespół nie wie, kto rozstrzyga zakres i spójność modelu.
- Obraz bez źródła. Nie da się łatwo odtworzyć ani poprawić diagramu.
- Aktualizacja zrzutu zamiast modelu. Źródło i wynik powinny pozostać zgodne.
- Test renderowania uznany za recenzję semantyki. Poprawna składnia nie gwarantuje prawdziwego modelu.
- Nieaktualny diagram pozostawiony bez oznaczenia. Odbiorcy mogą traktować go jak obowiązujący.
Podsumowanie#
Aktualizuj diagram, gdy zmienia się informacja, którą ma przekazywać, i włącz jego przegląd do procesu zmian systemu. Określ właściciela, źródło prawdy i zdarzenia aktualizujące. Po modyfikacji sprawdź nie tylko renderowanie, lecz także semantykę, spójność i użyteczność widoku.