ADR – Architektoniczne Decyzje Projektowe

Witajcie na moim blogu! Dziś chciałbym podzielić się z Wami czymś, co może znacząco ułatwić Wam pracę nad projektami programistycznymi – Architektoniczne Decyzje Projektowe, czyli poznajmy czym jest ADR (ang. Architectural Decision Records).

ADR to prosta, ale niezwykle skuteczna metoda dokumentowania decyzji architektonicznych podejmowanych w trakcie rozwijania projektu. Pozwala ona na utrzymanie przejrzystości i spójności w zespole, a także na lepsze zrozumienie podejmowanych kroków. Dzięki ADR, zarówno nowi członkowie zespołu, jak i Ci, którzy pracują nad projektem od dłuższego czasu, mogą łatwo śledzić ewolucję architektury i motywy stojące za konkretnymi decyzjami.

Dlaczego warto używać ADR?

Zachowanie kontekstu decyzji

Dokumentowanie decyzji wraz z ich kontekstem pomaga zrozumieć, dlaczego podjęto określone kroki w danym momencie. Często zdarza się, że po kilku miesiącach lub latach zapominamy, dlaczego podjęliśmy konkretne decyzje. Dzięki ADR, każda decyzja jest zapisana wraz z kontekstem, co pozwala na łatwe odświeżenie pamięci.

Ułatwienie komunikacji w zespole

ADR ułatwia dzielenie się wiedzą w zespole, zwłaszcza w dużych i złożonych projektach. Nowi członkowie zespołu mogą szybko zrozumieć, dlaczego architektura wygląda tak, a nie inaczej, co przyspiesza ich wdrożenie i zwiększa efektywność pracy.

Redukcja długu technicznego

Dzięki ADR możemy lepiej zarządzać długiem technicznym, śledząc, które decyzje mogą wymagać rewizji w przyszłości. Dokumentowanie kompromisów, które musieliśmy podjąć, pozwala na lepsze planowanie przyszłych zmian i uniknięcie pułapek związanych z niewłaściwymi decyzjami.

Wsparcie dla przyszłych zmian

Gdy projekt wymaga zmian, ADR stanowi cenną dokumentację, która ułatwia zrozumienie istniejącej architektury. Pozwala to na bardziej świadome podejmowanie decyzji i unikanie problemów wynikających z nieznajomości wcześniejszych decyzji.

Jak zacząć z ADR?

Rozpoczęcie pracy jest proste i nie wymaga zaawansowanych narzędzi. Możesz wykorzystać zwykłe pliki tekstowe, Markdown, czy dowolne inne narzędzie do dokumentacji. Oto kroki, które pomogą Ci zacząć:

Krok 1: Wybierz narzędzie do dokumentacji

Pierwszym krokiem jest wybór narzędzia, które będzie używane do tworzenia i przechowywania ADR. Najpopularniejsze opcje to:

• GitHub/ GitLab Wiki: Idealne również dla projektów open-source, ponieważ jest zintegrowane z repozytorium kodu.
• Notion: Elastyczne narzędzie do zarządzania dokumentacją, które umożliwia tworzenie złożonych struktur dokumentów.
• Confluence: Popularne w środowiskach korporacyjnych, oferuje rozbudowane funkcje do zarządzania dokumentacją.

Krok 2: Zdefiniuj proces tworzenia Architektoniczną Decyzję Projektową

Ustal, kto jest odpowiedzialny za tworzenie ADR i w jakich okolicznościach powinny być one tworzone. Może to być dedykowana osoba, lider zespołu lub każdy członek zespołu, w zależności od wielkości i struktury projektu.

Krok 3: Szkolenie zespołu

Przedstaw zespołowi ideę ADR i pokaż przykłady. Upewnij się, że wszyscy rozumieją, jak i dlaczego tworzymy ADR. Możesz zorganizować warsztaty lub prezentacje, aby wyjaśnić korzyści i proces tworzenia ADR.

Krok 4: Bądź konsekwentny

Regularnie aktualizuj ADR i upewnij się, że dokumentacja odzwierciedla rzeczywiste decyzje projektowe. ADR powinien być żywym dokumentem, który ewoluuje wraz z projektem.

Szablon Architektonicznej Decyzji Projektowej

Aby ułatwić Ci rozpoczęcie, oto przykładowy szablon, który możesz wykorzystać w swoim projekcie:

# [Numer ADR] [Tytuł]

**Data:** [Data]

**Status:** [Proponowane / Zaakceptowane / Odrzucone / Wdrożone]

## Kontekst
Opis kontekstu, w którym została podjęta decyzja. Co spowodowało, że ta decyzja była konieczna?

## Decyzja
Opis podjętej decyzji. Co zostało postanowione? Jakie są szczegóły tej decyzji?

## Konsekwencje
Opis konsekwencji podjętej decyzji. Jakie są pozytywne i negatywne skutki? Jakie mogą być przyszłe wyzwania wynikające z tej decyzji?

## Alternatywy
Opis rozważanych alternatyw i powodów, dla których zostały one odrzucone.

Zobacz również więcej przykładów bezpośrednio na repozytorium github Joel Parker Hendersona https://github.com/joelparkerhenderson/architecture-decision-record

Przykład ADR

Aby lepiej zobrazować, jak może wyglądać prosta Architektoniczna Decyzja Projektowa, poniżej przedstawiam przykładowy zapis na podstawie powyższego szablonu:

# 001 Wybór frameworka webowego dla nowego projektu

**Data:** 2023-06-22

**Status:** Zaakceptowane

## Kontekst
Rozpoczynamy nowy projekt, który będzie wymagał solidnego frameworka webowego. Kluczowe wymagania to szybkość, łatwość użycia oraz dobra dokumentacja.

## Decyzja
Zdecydowaliśmy się użyć Django jako frameworka webowego. Django oferuje kompletne rozwiązanie z doskonałą dokumentacją, co pozwala na szybki rozwój i wdrożenie.

## Konsekwencje
- **Pozytywne:** Szybki rozwój dzięki wbudowanym funkcjom, duża społeczność i wsparcie.
- **Negatywne:** Może być nadmiarowe dla prostych aplikacji, wymaga nauki specyficznych dla Django konwencji.

## Alternatywy
- **Flask:** Rozważany, ale odrzucony ze względu na brak wbudowanych funkcji, które są standardowo dostępne w Django.
- **FastAPI:** Nowoczesny i szybki, ale z mniejszą społecznością i dokumentacją w porównaniu do Django.

Korzyści z ADR

Przejrzystość i spójność

Każdy członek zespołu może łatwo śledzić ewolucję architektury projektu. To zwiększa przejrzystość i spójność, co jest szczególnie ważne w dużych i złożonych projektach. Nowi członkowie zespołu mogą szybko zrozumieć, dlaczego architektura wygląda tak, a nie inaczej, co przyspiesza ich wdrożenie.

Lepsza komunikacja

Architektoniczne Decyzje Projektowe ułatwią komunikację w zespole. Każda decyzja jest udokumentowana i dostępna dla wszystkich, co redukuje potrzebę ciągłego tłumaczenia tych samych rzeczy nowym członkom zespołu czy interesariuszom. To również ułatwia dyskusje na temat przyszłych zmian, ponieważ każdy ma dostęp do pełnej historii decyzji.

Zarządzanie długiem technicznym

Dokumentowanie decyzji architektonicznych pomaga lepiej zarządzać długiem technicznym. Dzięki ADR możemy śledzić, które decyzje były kompromisami, które mogą wymagać rewizji w przyszłości. Pozwala to na lepsze planowanie i unikanie problemów wynikających z przestarzałych lub niewłaściwych decyzji.

Wsparcie dla przyszłych zmian

Architektoniczne Decyzje Projektowe stanowią cenną dokumentację, która ułatwia zrozumienie istniejącej architektury projektu. Gdy projekt wymaga zmian, ADR umożliwia świadome podejmowanie decyzji i unikanie problemów wynikających z nieznajomości wcześniejszych decyzji. To również ułatwia wdrażanie nowych członków zespołu i przyspiesza ich integrację.

Dobre praktyki

Poniżej zebrałem dobre praktyki przy tworzeniu takiego pliku.

Uzasadnienie

Wyjaśnij powody podjęcia konkretnej decyzji architektonicznej (AD). Można tu uwzględnić kontekst, zalety i wady różnych potencjalnych wyborów, porównania funkcji, dyskusje na temat kosztów i korzyści oraz inne istotne informacje.

Konkretny

Każdy ADR powinien dotyczyć jednej decyzji architektonicznej, a nie wielu decyzji jednocześnie. To pomaga w utrzymaniu klarowności i przejrzystości dokumentacji.

Znaczniki czasowe

Identyfikuj, kiedy każdy element ADR został napisany. Jest to szczególnie ważne dla aspektów, które mogą zmieniać się w czasie, takich jak koszty, harmonogramy, skalowanie i tym podobne.

Niezmienność

Nie zmieniaj istniejących informacji w ADR. Zamiast tego, uzupełnij ADR o nowe informacje lub zastąp go tworząc nowy ADR. To zapewnia integralność dokumentacji i śledzenie historii decyzji.

Cechy dobrego „Kontekstu” w ADR

• Wyjaśnij sytuację i priorytety biznesowe Twojej organizacji.
• Uwzględnij uzasadnienie i rozważania oparte na społecznym i kompetencyjnym składzie zespołów.
• Uwzględnij istotne zalety i wady oraz opisz je w kontekście Twoich potrzeb i celów.

Cechy dobrej sekcji „Konsekwencje” w ADR

• Wyjaśnij, co wynika z podjęcia decyzji. Mogą to być efekty, wyniki, produkty, działania następcze i inne.
• Uwzględnij informacje o wszelkich kolejnych ADR. Często zdarza się, że jeden ADR wywołuje potrzebę tworzenia kolejnych ADR, na przykład gdy jedna decyzja tworzy konieczność podjęcia kilku mniejszych decyzji.
• Uwzględnij wszelkie procesy przeglądu po zakończeniu działania. Zespoły często przeglądają każdy ADR miesiąc po jego utworzeniu, aby porównać informacje z ADR z rzeczywistością i wyciągnąć wnioski na przyszłość.

Nowy ADR może zastąpić poprzedni ADR

Gdy podejmowana jest decyzja, która zastępuje lub unieważnia wcześniejszy ADR, należy stworzyć nowy ADR. To pozwala na aktualizację dokumentacji bez utraty historii decyzji.

Podsumowanie

Architektoniczne Decyzje Projektowe to potężne narzędzie, które może znacząco poprawić jakość i przejrzystość procesu podejmowania decyzji w projektach programistycznych. Dokumentowanie decyzji architektonicznych pomaga zachować kontekst, ułatwia komunikację w zespole, redukuje dług techniczny i wspiera przyszłe zmiany.

Zachęcam Was do wypróbowania tej dobrej praktyki w swoich projektach. Zacznijcie od prostego szablonu i dostosujcie go do swoich potrzeb. Przekonacie się, jak bardzo może to ułatwić Wam pracę i zwiększyć efektywność zespołu. Jeśli macie jakieś pytania lub chcecie podzielić się swoimi doświadczeniami, zostawcie komentarz poniżej.

Do zobaczenia w kolejnym wpisie!